Next Basic Chat

examples/next-basic-chat is the smallest complete example for adding Vela SDK to an existing Next.js + AI SDK chat route.

Files To Read

path	Role
examples/next-basic-chat/app/api/chat/handler.ts	Main Vela integration for the chat POST route
examples/next-basic-chat/app/api/vela/readiness/route.ts	Authorization-free readiness endpoint
examples/next-basic-chat/lib/vela-scope.ts	Stores, clears, and serializes Hosted Connect return scope into the request body
examples/next-basic-chat/app/api/chat/route.test.ts	Tests for missing env, missing scope, blocked, deny, and allow paths

Route Structure

1. Call getVelaEnvironmentDiagnostics() before reading the request body.
2. Restore scope from the body vela object with resolveVelaExecutionScope().
3. Bind scope with createVelaIntegration({ client, executionScope }).
4. Create the non-allow response with prepareExecutionWithResponse().
5. Use the @vel4ai/ai-sdk and ai runtime only after allow.
6. Share execution.createResultReporter() between stream callbacks and the catch block.

Local Dogfood

pnpm dev:vela
pnpm dev:next-basic-chat
pnpm dev:assistant-ui-demo

Surface	URL
Vela control plane	http://localhost:4000
Next basic chat	http://localhost:3000
assistant-ui demo	http://localhost:4100

Start only one demo surface on port 4100 at a time. pnpm dev:ai-app and pnpm dev:assistant-ui-demo use the same port, so prefer pnpm dev:assistant-ui-demo during SDK dogfood work.