Next.js 16 + MongoDB Atlas + Kinde Auth + Mongoose ODM - CLAUDE.md Template

Overview

Direct answer: This CLAUDE.md Template provides a complete Claude Code instruction set to scaffold a Next.js 16 app with MongoDB Atlas, Kinde authentication, and Mongoose ODM. It is tailored for developers building a secure production-grade full-stack app.

The CLAUDE.md Template for Next.js 16 + Atlas + Kinde + Mongoose ODM covers end-to-end structure and serves as a paste-ready instruction block for Claude Code.

When to Use This CLAUDE.md Template

• You need a ready-to-paste Claude Code block to scaffold a Next.js 16 app with Atlas and Kinde authentication.
• You want consistent architecture rules for Mongoose-based data access in Atlas.
• You aim to onboard teammates with a shareable, stack-specific template.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Full-Stack Engineer building a modern Next.js 16 app with Atlas, Kinde, and Mongoose ODM.
Architecture rules:
- Use Next.js 16 App Router.
- Use Mongoose for MongoDB Atlas schemas and queries.
- Use Kinde OAuth as the authentication provider.
- Use environment variables for secrets; do not hard-code.
- Use HTTP-only cookies for session management.
- Use API routes for server-side data access; SSR/SSG where appropriate.
File structure rules:
- Put app pages in app/ with route-based file system.
- Keep models in src/models/ with Mongoose schemas.
- Keep services in src/services/ for DB access and Kinde client.
- Use middleware/auth for protected routes.
Authentication rules:
- Use Kinde credentials from env: KINDE_DOMAIN, KINDE_CLIENT_ID, KINDE_CLIENT_SECRET, KINDE_REDIRECT_URI.
- Implement OAuth 2.0 flow: authorization code grant; store tokens securely in httpOnly cookies.
- Validate ID tokens and map to user profile in DB.
Database rules:
- Connect to MongoDB Atlas via MONGODB_URI; use new URL parser and unified topology.
- Define Mongoose models for User, Session, and domain entities.
- Enforce unique indexes on email; validate required fields.
Validation rules:
- Validate inputs in API handlers with Mongoose schema validation.
- Use server-side validation for critical fields before DB writes.
Security rules:
- Do not expose secrets; rotate keys periodically.
- Enforce CSRF protection for stateful endpoints.
- Disable debug in production; use TLS everywhere.
Testing rules:
- Write unit tests for DB models using in-memory MongoDB or test containers.
- Write integration tests for auth flow with Kinde mocks.
- Add end-to-end tests for critical user journeys.
Deployment rules:
- Deploy to Vercel or similar hosting; set env vars in deployment settings.
- Use separate prod/stage env files; ensure migrations run in CI if needed.
Things Claude must not do:
- Do not embed secret keys in code blocks.
- Do not bypass OAuth flow or skip token validation.
- Do not rely on in-memory DB for production data.

Recommended Project Structure

/apps/nextjs-mongo-kinde/
  app/
  pages/
  src/
    models/
    services/
    lib/
    middleware/
  public/
  .env.local
  package.json
  next.config.js

Core Engineering Principles

• Secure by default: protect secrets, validate inputs, and enforce least privilege.
• Explicit boundaries: clear separation between app, data models, and auth.
• Type-safe code: prefer TypeScript and strongly typed contracts between layers.
• Idempotent deployments: reproducible builds and environment parity.

Code Construction Rules

• Use Next.js 16 App Router with TS in a single monorepo layout.
• Leverage Mongoose ODM for data access to Atlas clusters.
• Integrate Kinde Auth for OAuth 2.0; store tokens securely in httpOnly cookies.
• Store config in environment variables; never hard-code secrets.
• Validate inputs server-side and enforce schema-level validation.
• Ensure endpoints are protected and implement role checks where needed.

Security and Production Rules

• Use HTTPS in all environments; enforce secure cookies (secure flag).
• Enable CSRF protection for state-changing operations.
• Rotate credentials periodically; do not commit secrets.
• Apply content security policy and strict transport security headers.

Testing Checklist

• Unit tests for Mongoose models with isolated tests.
• Integration tests for auth flows using Kinde mocks.
• End-to-end tests for primary user journeys (signup, login, protected routes).
• CI checks for lint, tests, and type checks; ensure production build passes.

Common Mistakes to Avoid

• Hard-coding secrets in code blocks or source files.
• Skipping token validation or OAuth flow checks.
• Using in-memory databases for production data.
• Overrelying on client-side validation for security-critical fields.

FAQ

What is a CLAUDE.md Template for this stack?

A copyable Claude Code instruction block that configures Next.js 16 with MongoDB Atlas, Kinde Auth, and Mongoose ODM.

How do I configure Kinde Auth in this template?

Set KINDE_DOMAIN, KINDE_CLIENT_ID, KINDE_CLIENT_SECRET, and KINDE_REDIRECT_URI in your environment and wire OAuth code flow to your Next.js app.

How do I connect MongoDB Atlas with Mongoose?

Provide MONGODB_URI in the environment; use Mongoose.connect with proper options; define schemas under src/models/.

Where should I place secrets and env vars?

In a .env.local file for local development and in your hosting provider's secret management for production.

How do I deploy this template in production?

Use a modern hosting service like Vercel; configure env vars in the dashboard; ensure the app runs with a production build and secure cookies.