Skip to main content
Use this page when you want a small Next.js chat app that feels real, but still keeps your Phaseo API key on the server.

Build a Next.js web chat app on top of Phaseo Gateway.

Open in Cursor

​
Sample project

​
What this app does

  • fetches available models from GET /v1/models
  • submits chat turns through POST /v1/responses
  • keeps the API key on the server
  • gives you a simple starting point for a real product without OAuth complexity

​
Key files

  • app/api/models/route.ts
  • app/api/responses/route.ts
  • app/components/ChatClient.tsx
  • lib/gateway.ts

​
Why the sample is structured this way

​
1. The browser does not call Phaseo directly

The UI talks to your own Next.js routes first. Those routes call Phaseo on the server. This gives you:
  • server-side secret handling
  • one place to manage headers and request payloads
  • an easier upgrade path if you later add auth, rate limits, or logging

​
2. Model discovery is separated from generation

Keep model listing and chat generation in separate routes so each part stays easy to understand:
  • one route for listing models
  • one route for running the chat request

​
3. The UI owns interaction state only

The React client handles:
  • input state
  • loading state
  • error presentation
  • rendered messages
The server route handles the AI call. The browser just handles the user experience.

​
Run the sample

cd examples/web-chat-nextjs
npm install
cp .env.example .env.local

cd examples/web-chat-nextjs
pnpm install
cp .env.example .env.local

cd examples/web-chat-nextjs
yarn install
cp .env.example .env.local

cd examples/web-chat-nextjs
bun install
cp .env.example .env.local
Set:
  • PHASEO_API_KEY
  • NEXT_PUBLIC_GATEWAY_URL
Then run: 
npm run dev

pnpm dev

yarn dev

bun run dev
Open http://localhost:3000.

​
How to make it your own

  • switch the default model to your chosen production target
  • add streaming if your UX needs token-by-token output
  • add auth later if the app becomes multi-user
  • swap the server route internals to the TypeScript SDK later if you want a higher-level client

​
When to use a different starting point

  • use the Node quickstart when you want a script or backend smoke test, not a UI
  • use the Python quickstart when the first integration lives in a worker, CLI, or backend service
Last modified on July 9, 2026