CLAUDE.md Template: Nuxt 4 + MongoDB + Kinde Auth + Mongoose ODM

Overview

The CLAUDE.md template is a copyable Claude Code blueprint that guides you to scaffold a Nuxt 4 project with MongoDB using Mongoose ODM and Kinde Auth for authentication. It covers frontend, server API endpoints (Nitro), and secure data access patterns suitable for modern full-stack Nuxt apps.

Stack covered: Nuxt 4, MongoDB, Kinde Auth, Mongoose ODM.

When to Use This CLAUDE.md Template

• You need a production-ready Nuxt 4 app with a MongoDB backend secured by an identity provider (Kinde).
• You want an integrated Mongoose ODM layer for user data, roles, and session state.
• You require a server API under Nuxt Nitro to handle data fetch/mutate with proper auth guards.
• You plan to deploy to a container or serverless environment and need a clear, repeatable structure.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code, a code generation assistant. Produce a Nuxt 4 + MongoDB + Kinde Auth + Mongoose ODM project scaffold suitable for Claude Code execution.

Architecture rules:
- Frontend and backend live in a single repository with Nuxt 4 as the frontend and Nitro server for API endpoints.
- MongoDB is accessed via Mongoose ODM. Use a single shared connection helper exported from a dedicated module.
- Kinde Auth is integrated on the frontend (Kinde SDK) and enforced on protected Nitro API routes via middleware.
- All secrets must live in environment variables; never embed credentials in the Claude output.
- Use TypeScript end-to-end for type safety; API routes typed with zod for input validation.
- Separate concerns: models under a dedicated folder, API handlers under server/api, and utilities under lib.

File structure rules:
- Frontend lives under nuxt-app/ (Nuxt 4 project).
- Backend API lives under nuxt-app/server/api/ for Nitro endpoints.
- Shared DB client under nuxt-app/lib/mongo.ts.
- Mongoose models under nuxt-app/models/ or nuxt-app/server/mongoose/models.
- Kinde config under nuxt-app/kinDe/ and plugin/ middleware for auth checks.

Authentication rules:
- Frontend uses Kinde Sign-In with redirect; refresh tokens stored in HTTP-only cookies.
- Protected API routes require a valid Kinde JWT and session; reject requests with missing/invalid tokens.
- Do not expose tokens to the browser; always validate on server side.
- Provide a sign-out flow that clears cookies and ends the session.

Database rules:
- Use Mongoose to define User schema with unique email, hashed password, and createdAt/updatedAt timestamps.
- Passwords must be stored using bcrypt with a salted hash.
- Validation at the model and API layer to enforce required fields and allowed formats.

Validation rules:
- Use Zod for API payload validation on server/api endpoints.
- Normalize input (trim strings, normalize emails) before persistence.
- Return uniform error structures with error codes.

Security rules:
- Use HTTPS in production; set secure cookies (Secure; SameSite=Lax/Strict as appropriate).
- Enable CSRF protection where necessary for state-changing requests.
- Implement rate limiting on public endpoints and protect sensitive routes.
- Do not log sensitive data; redact tokens and passwords in logs.

Testing rules:
- Unit test Mongoose models (Jest/Vitest) focusing on validation and hooks.
- Integration tests for API endpoints with Supertest or Vitest, mocking Kinde tokens.
- E2E tests for login flows using Cypress/Playwright against a test environment.

Deployment rules:
- Use environment variables for MONGODB_URI, KINDE_CLIENT_ID, KINDE_CLIENT_SECRET, and JWT secrets.
- Build with: npm run build (Nuxt) + appropriate server configuration for Nitro.
- Ensure server/api endpoints are reachable behind proper CORS and auth guards.

Things Claude must not do:
- Do not generate code that uses Prisma or unrelated ORMs.
- Do not bypass Kinde authentication checks in API routes.
- Do not embed real credentials in the template output.
- Do not assume a specific deployment platform; keep deployment instructions generic with environment variables.

Recommended Project Structure

nuxt-app/                 # Nuxt 4 frontend project
├── nuxt.config.ts
├── package.json
├── app.vue
├── pages/
├── components/
├── layouts/
├── composables/
├── plugins/
├── server/
│   └── api/
│       ├── users.ts
│       └── auth.ts
├── lib/
│   └── mongo.ts
├── models/
│   └── user.ts
├── kinDe/
│   └── kinDeConfig.ts
└── .env.local

backend/                    # Optional backend extension or separate services
├── mongoose/
│   ├── models/
│   │   └── user.ts
│   ├── schemas/
│   └── index.ts
└── README.md

Core Engineering Principles

• Type safety across frontend and backend (TypeScript).
• Explicit data contracts and input validation (Zod on API boundaries).
• Security by design: proper auth, token handling, and secure cookies.
• Separation of concerns: clear boundaries between UI, API, and data models.
• Idempotent and retry-friendly API design; deterministic builds.
• Observability: structured logging and simple metrics for critical APIs.

Code Construction Rules

• Use Nuxt 4 conventions for pages, layouts, and server routes; keep server logic in server/api.
• Centralize DB connection in lib/mongo.ts and reuse it in API handlers.
• Define Mongoose models (e.g., User) in a dedicated models folder and export types for use in API endpoints.
• Validate all incoming payloads with Zod; return consistent error shapes.
• Authenticate protected routes with Kinde tokens and verify on server side.
• Do not hardcode secrets; always read from environment variables.

Security and Production Rules

• Use HTTP-only, Secure cookies for session tokens; set SameSite appropriately.
• Rotate tokens and implement short-lived access tokens with refresh tokens.
• Enable CSRF protection for state-changing endpoints; validate origins in production.
• Limit request rates on public endpoints; use helmet-like protections and HTTP headers.
• Audit logs and redact sensitive data in logs.

Testing Checklist

• Model tests verify validation, hashing, and timestamps.
• API integration tests cover authentication, user CRUD, and error cases.
• End-to-end tests simulate login, access to protected routes, and logout flows.
• CI should run type checks, unit tests, and a lightweight E2E smoke test.
• Production readiness checks: environment variables, TLS, and proper build.

Common Mistakes to Avoid

• Storing plaintext passwords or secret keys in code or repo history.
• Relying on client-side only auth checks; server-side validation is mandatory.
• Overexposing API endpoints without proper authentication guards.
• Ignoring Mongoose connection lifecycles or not handling connection errors gracefully.
• Hard-coding MongoDB URIs; always use environment variables.

FAQ