Pick the framework you already chose. Keep its routes, middleware, logging, data layer, and build command. Agentuity adds service clients, local development, and deploy packaging on top of those conventions.
Framework Guides
Start with the framework that owns your routes and build command. Each guide keeps the framework conventions in place and adds Agentuity only at the server boundary.
Choose a Starting Point
| Path | Use when | Start with |
|---|---|---|
| Create a new Agentuity starter | You want Agentuity to scaffold one of the five built-in starters and example routes. | npm create agentuity -- --framework nextjs --services keyvalue |
| Add Agentuity to a new framework app | You just created the app with the framework's own CLI. | npm install -D @agentuity/cli and npm install @agentuity/keyvalue |
| Add Agentuity to an existing app | The app already has routes, scripts, env files, and a working build. | Add Agentuity to an existing app |
How the Framework Shape Works
Keep the framework's normal file conventions. Agentuity overlays service clients, dev environment wiring, and deploy metadata. It does not replace the router.
| Framework | Route shape | Add Agentuity through |
|---|---|---|
| Next.js | app/api/**/route.ts | standalone service clients |
| Nuxt | server/api/*.ts Nitro handlers | standalone service clients |
| React Router | app/routes.ts plus route modules | standalone service clients |
| SvelteKit | +server.ts routes and server actions | standalone service clients |
| Astro | src/pages/api/*.ts endpoints | standalone service clients |
| Hono | new Hono() routes | standalone clients or @agentuity/hono |
| Vite + React | browser UI with a server boundary | standalone service clients |
| TanStack Start | server routes and server functions | standalone service clients |
agentuity dev runs your package manager's dev script with service credentials when the linked project key is available. agentuity build runs the framework build, packages the app, and writes .agentuity/launch.json when packaging succeeds. Treat that as a packaging check, then validate the packaged command locally before relying on server routes.
Framework Starters
npm create agentuity -- --framework <slug> scaffolds these starters:
| Slug | Framework |
|---|---|
nextjs | Next.js |
nuxt | Nuxt |
sveltekit | SvelteKit |
astro | Astro |
hono | Hono |
React Router, Vite + React, and TanStack Start are existing-framework adoption paths. Start with each framework's own CLI, then add @agentuity/cli, import the project, and verify agentuity build output before deploying.
Run the framework build when you want framework-only feedback, then run agentuity build, inspect .agentuity/launch.json, and start the packaged command locally before your first deploy. Use --skip-type-check only when iterating on packaging, not before a real deploy.
Before You Deploy
| Check | What it proves |
|---|---|
| upstream framework docs | route files, server handlers, adapters, and build output are idiomatic |
| local starter or app | the framework app runs before Agentuity packaging is involved |
agentuity build | the packaging step completes and writes .agentuity output |
.agentuity/launch.json plus local validation | the packaged command starts the process and routes you expect |
If a framework page calls out a detector fallback or packaging caveat, treat it as a deploy check: inspect the generated command and validate at least one server route before you ship it.
Add Services
Direct service clients are the portable default across supported frameworks. Use them in route handlers, server functions, workers, scripts, or CLIs that own the work:
npm install @agentuity/keyvalueimport { KeyValueClient } from '@agentuity/keyvalue';
const kv = new KeyValueClient();
await kv.set('sessions', 'current', { updatedAt: new Date().toISOString() });Hono apps can also install @agentuity/hono when middleware is a convenient injection point for shared clients and telemetry. Direct clients still work in Hono when a route or module needs to stay framework-portable.
Next Steps
- Services: choose storage, messaging, identity, observability, and execution clients
- Build: model calls, streaming routes, and background work patterns
- Deploying Apps: run your framework project with
agentuity devandagentuity deploy