Nuxt 3 Development Recipes

Nuxt 3 gives you file-based routing, auto-imports, server routes, and hybrid rendering out of the box. These recipes help you use AI tools to build on that foundation without fighting the framework’s conventions. Every prompt here produces code that respects Nuxt’s directory structure, leverages auto-imports, and handles SSR/CSR boundaries correctly.

What You Will Walk Away With

Server route recipes that handle auth, validation, and database access
Composable patterns for data fetching with useFetch and useAsyncData
Middleware and plugin recipes for auth guards and global state
Deployment prompts for Vercel, Cloudflare, and Netlify edge

Recipe 1: Server API Route with Zod Validation

Scenario: You need a POST endpoint for creating blog posts with Zod validation, auth checking, and proper error responses.

Create a Nuxt server route at server/api/posts.post.ts. Use defineEventHandler with readValidatedBody and a Zod schema for validation. The schema should require title (string, 3-200 chars), content (string, min 10 chars), categoryId (UUID string), tags (array of strings, max 5), and publishedAt (optional ISO date string). Check the Authorization header for a Bearer token, verify it using verifyJWT() from server/utils/auth.ts. If invalid, throw createError({ statusCode: 401, message: 'Unauthorized' }). On valid request, insert into the database using Drizzle ORM, return the created post with 201 status. Handle duplicate title with a 409 Conflict response. Write a companion test using $fetch from @nuxt/test-utils that covers valid creation, validation errors, auth failure, and duplicate title.

Expected output: Server route file, Zod schema, and test file with 4 test cases.

Recipe 2: Standardized Data Fetching Composable

Scenario: Your pages call useFetch directly with duplicated error handling. You need a composable that standardizes this.

Create composables/useApiData.ts that wraps Nuxt’s useFetch with consistent patterns. The composable should: (1) Accept a URL string and options object. (2) Automatically add the auth token from useState('auth-token') to the Authorization header. (3) Transform error responses into a typed ApiError object with statusCode, message, and optional field-level errors. (4) Provide refresh() that re-fetches, clear() that resets data, and retry() that retries after an error. (5) Handle SSR correctly: during server rendering, use the request event’s cookies for auth instead of useState. (6) Type the return as { data: Ref<T | null>, error: Ref<ApiError | null>, pending: Ref<boolean>, refresh, clear, retry }. Create typed wrappers: useApiGet<T>(url), useApiPost<T>(url, body), useApiPut<T>(url, body), useApiDelete(url). Test that the composable handles SSR payload deduplication and client-side reactivity.

Expected output: Composable file with typed wrappers, ApiError type, and tests.

Recipe 3: Auth Middleware with JWT Refresh

Scenario: Protected pages need to check authentication and transparently refresh expired tokens without redirecting the user.

This scaffold spans two middleware files, a plugin, and a composable — and the SSR-vs-client split (cookie on the server, useState on the client) is where AI tools quietly produce a hydration mismatch. Pick the workflow that lets you catch it.

Use agent mode to generate middleware/auth.ts, middleware/guest.ts, the plugin, and useAuth() together, then checkpoint before accepting. Auth refresh is the classic spot where the AI reads document.cookie during SSR — the inline diff lets you catch the browser-only API in setup before it crashes the server render.

Generate the whole auth surface headless, then guard the SSR boundary with a hook: add a PostToolUse hook on middleware/*.ts and plugins/*.ts that greps for document. or window. outside an onMounted/import.meta.client guard and fails the edit. Run claude -p "build the auth middleware, guest middleware, plugin, and useAuth composable" so the transparent-refresh path lands in one turn.

Create three pieces: (1) middleware/auth.ts — a named route middleware that checks for a valid auth token in useState('auth'). If missing, redirect to /login with a redirect query param preserving the original URL. If the token is expired (check exp claim), call the refresh endpoint before allowing navigation. If refresh fails, clear auth state and redirect to login. (2) middleware/guest.ts — for login/register pages, redirect to /dashboard if already authenticated. (3) plugins/auth.ts — a Nuxt plugin that runs on app init, checks for an existing refresh token in cookies, and silently restores the session. On the server side, read the cookie from the event; on the client side, read from document.cookie. (4) A useAuth() composable that exposes login(email, password), register(data), logout(), refreshToken(), and user computed ref. Protect pages by adding definePageMeta({ middleware: 'auth' }). Test the full flow: login sets tokens, middleware blocks unauthenticated access, token refresh happens transparently, logout clears everything.

Expected output: Two middleware files, one plugin, one composable, and integration tests.

Recipe 4: Custom Nuxt Module for SEO

Scenario: Every page needs consistent meta tags, structured data, and an auto-generated sitemap.

Expected output: Module directory with index.ts, composable, Nitro plugins for sitemap and robots, and tests.

Recipe 5: Hybrid Rendering Configuration

Scenario: Your marketing pages should be static, your dashboard SSR, and your blog ISR with 1-hour revalidation.

Expected output: Updated nuxt.config.ts, render mode composable, and debug page.

Recipe 6: Real-Time Updates with Server-Sent Events

Scenario: Your dashboard needs live updates for order status changes without WebSocket complexity.

Implement SSE in Nuxt. (1) Create server/api/events.get.ts that returns an SSE stream using setResponseHeader(event, 'content-type', 'text/event-stream') and setResponseHeader(event, 'cache-control', 'no-cache'). Use createEventStream(event) from h3. Subscribe to a Redis pub/sub channel for order updates and push each update as an SSE event with JSON data. Handle client disconnection by cleaning up the Redis subscription. (2) Create composables/useSSE.ts wrapping EventSource with auto-reconnect, typed message parsing, and cleanup on component unmount. (3) Create composables/useOrderUpdates.ts that uses useSSE, filters for the current user’s orders, and updates the Pinia store reactively. (4) Show a toast notification when an order status changes. Test the SSE endpoint responds with correct headers and streams events.

Expected output: SSE server route, two composables, Pinia integration, and tests.

Recipe 7: Shared Nuxt Layer for Multi-App Reuse

Scenario: Three Nuxt apps share components, composables, and styles. You need a shared layer.

Expected output: Layer directory with config, 7 components, 3 composables, Tailwind preset, and integration test.

Recipe 8: Database Layer with Drizzle ORM

Scenario: Your Nuxt app needs type-safe database queries, migrations, and seeding.

The database layer is schema plus typed queries plus a seed script plus migration config — a lot of files that must agree on the same types. The relations and the migration step are where tooling choice matters.

Use agent mode to generate schema.ts, the query functions, and seed.ts in one pass, watching the inline diffs so the foreign-key references (authorId references users) actually line up. Run drizzle-kit generate from the integrated terminal and review the produced SQL migration before applying.

Generate the schema and queries headless, then make the contract enforceable: add a PostToolUse hook on server/db/schema.ts that runs drizzle-kit generate so the migration never drifts from the schema. Pipe the seed run’s output back in if Faker data violates a constraint — the terminal loop makes that one command.

Build the DB layer in a worktree so an in-progress migration never touches your shared dev database, then push and let the Cloud reviewer check that every query is parameterized and the getPostsWithAuthor join paginates correctly before merge.

Set up Drizzle ORM with PostgreSQL in Nuxt. (1) Create server/db/schema.ts with tables: users (id uuid, email unique, name, hashedPassword, role enum, createdAt), posts (id uuid, title, slug unique, content text, authorId references users, status enum draft/published/archived, publishedAt, createdAt), comments (id uuid, postId references posts, authorId references users, content text, createdAt). (2) Create server/db/index.ts initializing the drizzle client from environment variable. (3) Create server/db/queries/ with typed functions: getUserByEmail(email), getPostsWithAuthor(page, pageSize), createPost(data), getPostBySlug(slug) with author and comment count. (4) Create drizzle.config.ts for migrations. (5) Create a seed script at server/db/seed.ts with 10 users, 50 posts, and 200 comments using Faker. (6) Add server/utils/db.ts providing a cached database instance. Test queries against a test database.

Expected output: Schema file, query functions, config, seed script, and query tests.

Recipe 9: Blog with Nuxt Content

Scenario: You want a blog powered by Markdown files with frontmatter, code highlighting, and table of contents.

Expected output: Nuxt Content config, sample posts, blog pages, custom prose component, RSS route, and tests.

Recipe 10: Cloudflare Workers Edge Deployment

Scenario: Deploy your Nuxt app to Cloudflare Workers with D1 database, KV caching, and R2 storage.

Configure Nuxt for Cloudflare Workers deployment. (1) Set nitro: { preset: 'cloudflare_module', cloudflare: { deployConfig: true } } in nuxt.config — the Workers (module) preset, which supports D1, KV, R2, and waitUntil, and auto-generates the wrangler config. Do NOT use cloudflare-pages here: that is the separate Pages target with a different build output and binding shape. (2) Create wrangler.toml with D1 database binding, KV namespace for sessions, and R2 bucket for uploads. (3) Create server/utils/cf.ts providing typed access to Cloudflare bindings via event.context.cloudflare.env. (4) Create a session middleware at server/middleware/session.ts reading/writing session data to KV with 24-hour TTL. (5) Create a file upload route at server/api/upload.post.ts storing files in R2 and returning a public URL. (6) Update database queries to use D1 instead of PostgreSQL. (7) Add wrangler.toml for local development with --local D1. Test locally with npx wrangler dev.

Expected output: Nitro config, wrangler.toml, binding utilities, session middleware, upload route, and D1 queries.

Recipe 11: Testing Strategy for Nuxt Apps

Scenario: Your Nuxt app has zero tests. You need coverage for components, server routes, and composables.

Standing up a test harness is config plus utilities plus the first batch of tests — and the value only lands when those tests actually run on every change, which is where the tool workflows diverge.

Use agent mode to write vitest.config.ts, the tests/utils/ helpers, and the first component tests, then run them in the integrated terminal and feed any mountSuspended failures back inline. The visual diff helps you confirm the test utilities match how your real pages mount.

The natural fit: generate the harness headless, then make tests non-optional with a PostToolUse hook that runs npm run test:unit after edits to *.vue or server/**. Use claude -p "write @nuxt/test-utils tests for these three composables and two server routes" and let it iterate against the failing output until green.

Expected output: Vitest config, test utilities, component tests, server route tests, composable tests, and updated scripts.

Recipe 12: Performance Optimization Audit

Scenario: Your Nuxt app scores 60 on Lighthouse. Page transitions feel slow and the bundle is over 1 MB.

Expected output: Updated nuxt.config, NuxtImg replacements, chunk splitting config, and performance comparison.

When Recipes Break

What Is Next

Vue.js patterns for component-level recipes
API patterns for designing APIs your Nuxt server routes consume
Database recipes for optimizing queries behind your server routes