Get access

Using Codex to Create a Node.js Web Application Boilerplate

admin
4 min read

The simplest route is a full-stack Next.js application. It runs on Node.js while keeping the pages, authentication, API routes, and styling in one project.

Codex works best when the prompt clearly states the outcome, constraints, acceptance criteria, and validation commands. That matches current official OpenAI prompting guidance, which recommends explicit success criteria and autonomy boundaries.

1. Prepare the project

Install:

  • Node.js 20 or newer
  • npm
  • Git
  • Codex desktop or Codex CLI
  • Optionally, Ollama for local inference

Create an empty directory and open it in Codex:

mkdir simple-chat-app
cd simple-chat-app
git init

Then give Codex the following prompt.

2. Copy-paste prompt for Codex

Build a complete, functional Node.js boilerplate for an AI-powered chat application with a look and feel similar to ChatGPT in the current directory. Treat this project as new source of true.

BRAND

Product name: AIAppStarter
Product description: A simple, secure starter for AI-powered applications.

Use this color system:

Primary colors:

- Primary purple: #4B49AC
- Light blue: #98BDFF

AUTONOMY

You are authorized to:

- Inspect the current directory.
- Create and edit project files.
- Install normal project dependencies.
- Initialize and seed the local database.
- Run non-destructive development and validation commands.
- Fix implementation-related test, type, lint, and build failures.

Do not:

- Deploy the application.
- Create external cloud resources.
- commit secrets, API keys, or populated databases.
- perform destructive Git or filesystem operations.
- stop after scaffolding; continue until validation passes or a concrete
  external blocker is identified.

When a minor implementation detail is unspecified, select a sensible,
secure default and continue.


Initially, create the following pages:

1. **Landing Page**
   - Include a hero section highlighting the use of natural language to interact with the application.
   - Include a top navigation bar with icons for toggling dark mode and accessing the login page.
2. **Login Page**
   - Support email/password authentication, Google OAuth, and Microsoft OAuth.
   - Use the following default credentials:
     - Username: `admin@mptwork.local`
     - Password: `admin`
   - Disable Google and Microsoft OAuth authentication if the required OAuth configuration information is not provided.
3. **Chat Page**
   - Initially, simply echo the user's input back into the chat conversation.
   - Ultimately, the application will connect to either a local or remote OpenAI-compatible LLM endpoint configured through environment variables.
4. **Settings Page**
   - Allow administrators to view and edit configuration parameters defined in the default `.env` file.
5. Put the Settings and Sign Out as the popup menu items when clicking on the user name on the bottom of the Sidebar

## Technology Stack

Use a modern, beginner-friendly stack:

- Next.js
- TypeScript
- Tailwind CSS
- SQLite and PostgreSQL
- Prisma
- Auth.js / NextAuth

## Chat Layout

The responsive layout should resemble the interaction model of ChatGPT:
```sql
+--------------------------------------------------+
| Top Navigation                                   |
+----------------+---------------------------------+
| Sidebar        | Chat Conversation               |
|                |                                 |
| New Chat       |                                 |
|                |                                 |
| Conversation   |                                 |
| History        |                                 |
|                |                                 |
|                |                                 |
| [Collapse]     |---------------------------------|
|                | Chat Input                      |
+----------------+---------------------------------+
```

The sidebar should be collapsible and expandable using a toggle icon.

When the sidebar is collapsed:

- Hide the logo, if present.
- Hide the conversation history and other sidebar content.
- Show only the icon used to expand the sidebar.

The layout should be responsive and work well on both desktop and mobile devices. 

## Implementation Notes:

1. All React useEffect callbacks must be synchronous and may return only a cleanup function or nothing.

3. Let Codex implement and validate

After submitting the prompt:

  1. Review the architecture summary Codex gives you.
  2. Approve dependency installation if the app requests permission.
  3. Let Codex create the files and run its checks.
  4. If it stops after scaffolding, send:
Continue with the implementation. Do not stop until the database is initialized,
the bootstrap user is seeded, echo chat works, and tests, typecheck, lint, and
the production build have been run. Fix any implementation-related failures.

Implemented the complete Plainchat boilerplate in ../POC/ai-app-starter.

Key features:

  • Responsive home and login pages
  • Hashed local credentials: admin@mptwork.local / admin
  • Disabled Google and Microsoft OAuth controls
  • Protected chat and settings pages
  • OpenAI, Ollama, and automatic echo fallback
  • Collapsible sidebar with account menu, Settings, and logout
  • Light, dark, and system themes
  • Server-side validation, rate limiting, security headers, and safe errors
  • Prisma/SQLite database with idempotent initialization and seed
  • Focused unit tests and complete setup documentation

Important files:

  • README.md
  • src/auth.ts
  • src/lib/llm.ts
  • src/app/api/chat/route.ts
  • src/components/chat-interface.tsx
  • prisma/schema.prisma
  • .env.example

Validation completed successfully:

  • 11 unit tests passed
  • TypeScript passed
  • ESLint passed
  • Production build passed
  • Seeded login returned HTTP 302
  • Protected chat page returned HTTP 200
  • Echo API returned Echo: smoke test
  • Browser rendering, disabled OAuth controls, and dark mode were verified

Start it with:

cd ai-app-starter
npm run dev

Then open http://localhost:3000.

Current limitations: conversations remain in browser memory, OAuth is intentionally disabled, and the in-memory rate limiter should be replaced with a shared store before distributed production deployment. The default password must also be changed before sharing or deployment.

4. Start the finished application

Codex should document the exact commands, but they will generally resemble:

cp .env.example .env.local
npm install
npm run db:migrate
npm run db:seed
npm run dev

Open:

http://localhost:3000

Sign in with:

Username: admin@mptwork.local
Password: admin

With no LLM variables configured, entering:

Hello

should return something like:

Echo: Hello

5. Configure OpenAI later

Set server-side variables in .env.local:

LLM_PROVIDER=openai
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=your_selected_model

The prompt directs Codex to use the official Node SDK and Responses API, which is the recommended API for modern multi-turn and tool-capable OpenAI workflows in the official OpenAI documentation.

Restart the development server after changing environment variables.

6. Configure Ollama later

Install Ollama, download a model, and configure:

ollama pull llama3.2
ollama serve
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llama3.2

Then restart the application.

Before putting the app on a shared network, change the bootstrap password, use PostgreSQL or another production database, replace the in-memory rate limiter with a shared store, configure HTTPS, and properly enable and validate the Google and Microsoft OAuth providers.