Next.js
Your Next.js app and your eve agent run side by side on the same domain. Pages go to Next.js, and requests to /eve/v1/* go to the agent. The agent runs as its own service, never inside the Next.js server. Your React code is the same whichever setup you pick below.
Choose a setup
There are two ways to connect the app and the agent. Both deploy as one Vercel project.
| Vercel services (recommended) | Next.js hosts the agent | |
|---|---|---|
| What you add | A root vercel.ts | A wrapper in next.config.ts |
| Run locally | vercel dev --local | next dev |
| Self-host | Run the app and agent yourself | next start runs both |
Start with Vercel services. Choose Next.js hosting when Next.js should run everything, for example when you add an agent to an existing Next.js app that deploys from the project root.
Create a chat app
From your agent project, run the Web Chat installer:
It asks three questions:
- Framework: choose Next.js.
- Hosting: choose Vercel services, or Next.js to have Next.js host the agent.
- Authentication: choose Sign in with Vercel, or set it up yourself. See Authenticate users.
In a project with several agents, add --agent <name> to pick the one the chat talks to.
The installer creates a Next.js app in apps/web/:
Start it with the command the installer prints:
| Command | Starts |
|---|---|
npm run dev:all | The app and the agent together (Vercel services) |
npm run dev:web | The app. With Next.js hosting, it starts the agent too |
npm run dev | The agent alone, in the eve terminal UI |
dev:all needs Vercel CLI 59.16.0 or newer, but not a linked project.
Before you deploy, replace the placeholder auth the installer generates. Until then, production browser requests get 401. See Authenticate users.
Add eve to an existing app
With Vercel services
Leave next.config.ts alone. Add a vercel.ts at the project root that tells Vercel where your app lives:
withEve adds your agents and their routes for you: /eve/v1/* for one agent, or /eve/<name>/v1/* for each agent in a workspace.
- Install
evein the rootpackage.json. - Remove any
vercel.json.
See Compose agents with other Vercel services for more options.
With Next.js hosting
Wrap your Next.js config:
withEve looks for your agent next to next.config.ts. If the agent lives somewhere else, point to it:
This setup needs Next.js 16 and React 19. See withEve options for the rest.
Build the chat UI
Call useEveAgent from a Client Component:
A real chat also needs to show tool calls, approvals, questions, and sign-ins. Without them, a turn that waits on the user can't continue. The generated chat handles all of these. To build your own, see Human-in-the-loop prompts and Sign-ins.
Give each conversation a URL
The generated chat gives every conversation its own address:
| URL | Shows |
|---|---|
/ | The landing page |
/s | A new, empty conversation |
/s/[sessionId] | A saved conversation, including any reply still in progress |
The conversation page passes its session ID to the hook:
Three things to get right:
-
Change the URL without the router. Once
/screates a session, switch the address to/s/{sessionId}with the browser's ownreplaceState. Next.js patcheswindow.history, and going through its router would remount the page and cut off the reply: -
Use a
keyto switch conversations. Keying the chat on the session ID gives each conversation a fresh hook. -
Disable input while loading. While
statusis"resuming", show the messages but don't accept new ones.
Authenticate users
The browser calls the agent on your own domain, so it sends your app's cookies along. The agent checks them in agent/channels/eve.ts.
Replace the generated placeholderAuth() with a function that reads your app's session:
eve tries each entry in order:
appSessionaccepts your signed-in users.vercelOidc()accepts your own server code and the eve terminal UI.localDev()accepts requests during local development only.
For a public demo, none() from eve/channels/auth lets anyone in. Don't use it for private data. See Authentication for more.
If your app uses tokens instead of cookies, pass them to the hook:
Sign in with Vercel
Choose Sign in with Vercel in the installer to let members of your Vercel team sign in, with nothing to build. It needs a linked Vercel project. Local development skips sign-in. See Web Chat with Sign in with Vercel for details.
Save conversations
eve already keeps every conversation, so a URL with a session ID is enough to reopen one. Add your own database when you want a chat list, titles, or faster page loads.
Keep your chat record separate from the eve session. Your record holds the title and owner; eve holds the messages. Store the session and its events alongside your record:
Then:
- Create the chat record before the first message. If the user reloads mid-reply, the page can still find the conversation.
- Save as things happen. Save
sessioninonSessionChangeand each event inonEvent. Don't wait for the reply to finish: a turn waiting on the user hasn't finished. - Load on the server. Read the saved chat in a Server Component, and pass
eventsandsessionto the Client Component asinitialEventsandinitialSession, withresume: true. Saved messages show at once, and the live reply picks up from there. - Store
sessionas eve gives it to you. Don't compute the cursor from the number of events.
See Resume a saved session for how saved events and catch-up fit together.
Call the agent from server code
Route Handlers, Server Actions, and cron jobs can call the agent with Client from eve/client. Point it at your own domain, and sign requests with your project's Vercel OIDC token:
- Check who's calling before you call the agent, as above. The OIDC token gives your code the app's own access, so an unchecked route would let anyone use it.
- Install
@vercel/oidc, and runeve linkonce so the token works locally. - The token identifies your app, not a user. To act as the signed-in user, forward their cookie in
headersinstead. - Without an incoming request, as in a cron job, use
https://${process.env.VERCEL_URL}as the domain.
See Client SDK for more.
Use multiple agents
With several agents, each one gets its own path, such as /eve/support/v1/*. Pick one in the hook:
- Give each chat page one agent, and include the agent name in its URLs.
- Remount the chat when switching agents.
- Set up authentication for each agent.
Both setups find the agents in your project automatically. With Next.js hosting, you can also list agents that live elsewhere:
Use either eveRoot or agents, not both.
Run, build, and deploy
Run locally
- Vercel services:
npm run dev:all. - Next.js hosting:
npm run dev:web. Next.js starts the agent for you. To use an agent you already started, setEVE_BASE_URLto its address.
Deploy to Vercel
From the project root:
The app and each agent deploy together as one Vercel project. With Next.js hosting and an agents/ workspace, next build also writes .eve/agent-summary.json in the eveRoot directory, which Vercel uses to show each agent's tools, schedules, and connections on the project overview. See Deploy to Vercel for credentials and sandboxes.
Next.js hosting from apps/web
When the installer puts a Next.js-hosted app in apps/web/, Vercel doesn't build it by default.
In your Vercel project settings, set the Build Command to npm run build:web and the Output
Directory to apps/web/.next.
Run a production build locally
With Next.js hosting, next start runs the built agent too. Build both first:
The agent listens on port 4274. Set EVE_NEXT_PRODUCTION_PORT to change it.
With several agents, a root eve build doesn't build them for next start. Run eve build in each agents/<name>/ directory instead.
Self-host
- Vercel services: run the app and each agent with your own process manager and proxy. See Self-host eve.
- Next.js hosting:
next startruns the agent for you. To run the agent yourself instead, put it behind a proxy that serves it under the private path/_eve_internal/eve(theservicePrefixoption), then setEVE_NEXT_PRODUCTION_ORIGINto that proxy's address when you build and start Next.js.
Troubleshooting
| You see | Fix |
|---|---|
401 "Production auth is not configured" | Replace placeholderAuth(). See Authenticate users |
"The Next.js output directory .next was not found" on deploy | Set the Build Command and Output Directory. See Deploy to Vercel |
| The reply stops after the first message | Change the URL with History.prototype.replaceState. See Give each conversation a URL |
| Messages repeat or vanish after a reload | Save session from onSessionChange as is |
next dev times out waiting for the agent | Raise devServerTimeoutMs |
A custom channel route returns 404 with Vercel services | Route it to the agent in vercel.ts. See Compose agents |
Reference
withEve options
Options for withEve from eve/next. All are optional.
| Option | Default | Purpose |
|---|---|---|
eveRoot | The Next.js app root | Where your agent project lives |
agents | Found automatically | Agents to mount at /eve/<name>/v1/*. Each is a path or { root, buildCommand?, servicePrefix? } |
eveBuildCommand | Runs the installed eve | Command that builds each agent |
devServerTimeoutMs | 180000 | How long next dev waits for each agent to start |
servicePrefix | "/_eve_internal/eve" | Private route path for self-hosted proxying and hand-written Vercel services |
Environment variables
| Variable | Purpose |
|---|---|
EVE_BASE_URL | Next.js hosting, development: use an agent you already started |
EVE_NEXT_PRODUCTION_PORT | Next.js hosting: first port for agents that next start runs. Defaults to 4274 |
EVE_NEXT_PRODUCTION_ORIGIN | Next.js hosting: address of a proxy serving your agents under servicePrefix. Turns off automatic startup |
EVE_PUBLIC_ROUTE_PREFIX | Self-hosting: an agent's public path, such as /eve/support, so callback links work |
What to read next
- Frontend overview: everything the chat hook can do
- Authentication: checking who's calling
- Deploy to Vercel: services, credentials, and sandboxes
- Client SDK: calling the agent from server code