Nuxt 4 + Neo4j + Auth.js (Nuxt Auth) + Neo4j Driver Setup — CLAUDE.md Template

Overview

CLAUDE.md Template is a copyable Claude Code template that helps developers implement Nuxt 4 + Neo4j + Auth.js (Nuxt Auth) with the official Neo4j driver. It provides a complete set of rules and a ready-to-paste CLAUDE.md block for this stack.

Direct answer: You get a self-contained Claude Code instruction block that ensures secure authentication integration of Nuxt 4 with Neo4j via Auth.js, plus a production-oriented project structure and tests.

When to Use This CLAUDE.md Template

• Starting a Nuxt 4 + Neo4j app that requires user authentication with Neo4j as the source of truth.
• Standardizing how to wire Auth.js (Nuxt Auth) to the Neo4j driver across environments (dev, staging, prod).
• Creating a production-ready Claude Code block you can paste into CLAUDE.md for repeatable onboarding.
• Documenting security, testing, and deployment constraints specific to Nuxt 4 and Neo4j.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Architect and implement a Nuxt 4 app with Neo4j-backed authentication using Auth.js (Nuxt Auth) and the official Neo4j driver. Deliver a secure, testable integration ready for production.

Architecture rules:
- Use Nuxt 4 with Nitro server routes for auth endpoints.
- Centralize DB access in a single Neo4j driver instance per app instance.
- Use environment-based configuration for URIs and credentials.
- Use async/await and proper error handling.
- Do not bypass proxy or server-side validation for DB calls.

File structure rules:
- Keep driver and auth integration in a dedicated folder inside 'server' and 'neo4j' folder.
- Place all Nuxt pages under 'pages' with proper middleware.
- Do not scatter DB logic across components.

Authentication rules:
- Use Auth.js Nuxt module; configure with a custom strategy based on Neo4j user nodes.
- Enforce sessions with cookies and httpOnly flags; set secure in prod.
- Do not expose session tokens in frontend state without protection.

Database rules:
- Use Neo4j driver with connection pools; avoid plain text queries; use parameterized queries.
- Implement a user index and constraints to enforce unique usernames/emails.
- Do not perform untrusted string interpolation in Cypher queries.

Validation rules:
- Validate input data on server and client; enforce strict shapes for login and signup payloads.
- Return consistent error shapes and codes.

Security rules:
- Never log credentials; use env vars; disable stack traces in prod; use CSRF protection for endpoints where applicable.
- Rotate and store secrets securely in the hosting environment.

Testing rules:
- Unit tests for the Neo4j wrapper and Auth.js integration.
- Integration tests for login/logout flows and user persistence.
- Add basic end-to-end checks if the environment supports it.

Deployment rules:
- Secrets in environment variables; configure Nuxt to preload env vars; ensure Neo4j is accessible in the target env.
- Enable TLS for Neo4j connections in production.

Things Claude must not do:
- Do not expose driver credentials in code blocks.
- Do not use hard-coded sample users.
- Do not skip auth or validation checks.
- Do not bypass Neo4j transaction handling or error handling.

Recommended Project Structure

nuxt-app/
  - nuxt.config.ts
  - package.json
  - app/
  - components/
  - layouts/
  - pages/
  - plugins/
  - composables/
  - middleware/
  - server/
    - api/
      - auth.ts
      - neo4j.ts
      - user.ts
  - neo4j/
    - driver.ts
  - lib/
  - README.md

Core Engineering Principles

• Single source of truth: Neo4j is the authoritative data store for auth and user data.
• Explicit dependencies: all modules declare their DB and auth dependencies and are tested in isolation.
• Idempotent Claude Code: templates can be pasted multiple times without side effects.
• Security by default: secrets use env vars; no credentials in source; TLS enabled in prod.
• Environment-driven configuration: separate config for dev, staging, prod with clear overrides.

Code Construction Rules

• Use the official Neo4j driver; avoid alternative libraries unless required by stack constraints.
• Centralize DB access in a driver wrapper; export a single getSession or runCypher function.
• Configure Nuxt 4 with a dedicated serverMiddleware or Nitro route for auth flows.
• All Cypher queries must be parameterized; never interpolate user input directly.
• Keep authentication logic in a dedicated module or plugin; expose minimal public API.

Security and Production Rules

• Store sensitive values in environment variables; load via runtimeConfig or process.env.
• Set httpOnly and Secure cookies for sessions; enable SameSite policies in production.
• Disable verbose error stack traces in production; surface friendly error messages only.
• Validate inputs server-side on every auth request; reject malformed payloads.
• Encrypt and rotate secrets; monitor for suspicious auth activity; implement rate limiting.

Testing Checklist

• Unit tests for Neo4j driver wrapper and auth strategy implementations.
• Integration tests for sign-up, sign-in, token refresh, and user lookup against a test Neo4j instance.
• Contract tests for the Claude Code template outputs; ensure the block starts with "# CLAUDE.md".
• End-to-end tests for the login flow and protected routes if your CI supports it.
• Security scans and dependency checks before deployment.

Common Mistakes to Avoid

• Hard-coding credentials or sample users in code blocks.
• Using unparameterized Cypher queries leading to injection risks.
• Weak session handling or exposing session data to the client.
• Skipping environment-specific configuration and TLS in production.
• Neglecting test coverage for auth flows and DB interactions.

FAQ

What is the CLAUDE.md Template used for in this stack?

A copyable Claude Code block and best-practice guide for wiring Nuxt 4 to Neo4j via Auth.js (Nuxt Auth) and the Neo4j driver, with production-ready rules.

Which Nuxt 4 features are leveraged?

Nuxt 4 with Nitro server routes, ES modules, and a modular plugin system to integrate Auth.js and the Neo4j driver.

How should credentials be stored?

In environment variables; never commit secrets or credentials in CLAUDE.md blocks or code.

Can this template be adapted to serverless environments?

Yes; adapt the Nitro server routes and Neo4j connection strategy to suit serverless deployment constraints.

What tests are recommended?

Unit tests for DB wrapper and auth logic, integration tests for login flows, and optional end-to-end tests.