CLAUDE.md template: Nuxt 4 + Firebase Firestore + Firebase Auth + Pinia State Client | CLAUDE.md Template

Overview

A CLAUDE.md template for Nuxt 4 with Firebase Firestore, Firebase Auth, and Pinia State Client. This copyable Claude Code block scaffolds a secure, maintainable frontend architecture that teams can paste into Claude Code.

When to Use This CLAUDE.md Template

• Starting a Nuxt 4 project that uses Firebase for authentication and data storage
• Need a reproducible CLAUDE.md template for rapid onboarding
• Nesting Pinia as the single source of truth for client state

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are a Nuxt 4 frontend architect building a client app that uses Firebase Firestore for data storage, Firebase Auth for authentication, and Pinia for state management. Output a complete, ready-to-paste scaffold for Claude Code.

Architecture rules:
- Use Nuxt 4 with TypeScript, SSR enabled, and a clean separation between UI and data layers.
- Centralize Firebase config in environment variables; never commit keys to source.
- Pinia is the single source of truth for client state; use stores in /stores.
- All API calls go through a typed composable layer; avoid direct Firestore calls in components.
- Use server routes and Nitro helpers for data fetching where appropriate.

File structure rules:
- app/
  - layout/
  - components/
  - pages/
  - stores/
  - composables/
  - plugins/
  - firebase/
    - firebaseInit.ts
    - firebaseAuth.ts
    - firebaseFirestore.ts
  - types/
- middleware/
- tests/
- public/
- .env
- README Claude Code guidelines.md

Authentication rules:
- Use Firebase Auth with email/password and Google as a provider.
- Persist user state in Pinia; expose a user store with uid, email, displayName.
- Protect routes with a middleware guard that checks authState.
- Do not expose API keys or tokens to the client.
- Refresh tokens silently and handle sign-out cleanly.

Database rules:
- Firestore database rules require authentication for reads and writes by default.
- /users/{uid} data is readable and writable only by the owning user.
- Use serverTimestamp for createdAt/updatedAt fields.
- Do not trust client-only validation; enforce server-side validation.

Validation rules:
- Define runtime validation for all input using TypeScript types and explicit checks.
- Validate inputs before writing to Firestore; reject invalid data early.

Security rules:
- Firestore rules enforce auth and data ownership.
- Keep secrets on the server; never embed in client code.
- Enforce least privilege; no broad read/write access.

Testing rules:
- Unit tests with Vitest for stores and composables.
- Integration tests for API wrappers with mocked Firestore data.
- E2E tests with Playwright covering auth, data creation, and reading.

Deployment rules:
- Build with Nuxt 4 production configuration; set process.env variables in the environment.
- For SSR, deploy to a Node hosting that supports server bundles.
- Monitor and roll back on errors; ensure environment parity between CI and prod.

Things Claude must not do:
- Do not generate client-side secrets or hard-coded credentials.
- Do not bypass auth checks or improvise security bypasses.
- Do not generate server-side backdoors or insecure data exposure.
- Do not rely on non-existent libraries or deprecated APIs.
- Do not generate a monolithic single-file solution; keep modular structure.

Recommended Project Structure

app/
  layout/
  components/
  pages/
  stores/
  composables/
  plugins/
  firebase/
    firebaseInit.ts
    firebaseAuth.ts
    firebaseFirestore.ts
  types/
middleware/
tests/
public/

Core Engineering Principles

• Clear separation of concerns between UI, data, and state management (Nuxt 4 + Pinia).
• Type safety with TypeScript across stores, composables, and API layers.
• Security-first design, especially around authentication and Firestore rules.
• Reproducibility by providing a strict CLAUDE.md template that teams can paste into Claude Code.
• Observability and testability with unit, integration, and E2E tests.

Code Construction Rules

• Prefer TypeScript with strictNullChecks enabled.
• Use Pinia stores in /stores for all client-side state; avoid direct mutations in components.
• Encapsulate Firestore calls in a typed composable layer; export methods from /composables.
• Load Firebase config from environment variables; never commit keys.
• Validate input data in runtime and at the boundary before Firestore writes.
• Handle errors gracefully; propagate meaningful messages to the UI.

Security and Production Rules

• Firestore security rules must require authentication by default and enforce document ownership.
• Do not expose secrets or credentials in frontend code or logs.
• Use middleware guards to protect routes requiring authentication.
• Audit access patterns; log sensitive operations only on the server where appropriate.

Testing Checklist

• Unit tests for stores and composables with Vitest.
• Integration tests for Firebase API wrappers using mocked Firestore data.
• E2E tests for auth flow, data creation, and data reads with Playwright.
• CI pipeline runs build, runs tests, and verifies environment parity with staging.

Common Mistakes to Avoid

• Relying on client-side validation alone for security; enforce server-side checks in Firestore rules.
• Storing API keys or credentials in client code or env files not protected by server.
• Neglecting route guards and leaving sensitive pages unprotected.
• Using broad Firestore permissions that expose data to all users.
• Ignoring type safety; using any in stores or composables.

FAQ

Q: What does this CLAUDE.md template cover for Nuxt 4 with Firebase?

A: It provides a copyable Claude Code block and a stack-specific project structure tailored to Nuxt 4, Firebase Firestore, Firebase Auth, and Pinia.

Q: How should authentication be implemented?

A: Use Firebase Auth with providers, store user data in Pinia, and protect routes with middleware.

Q: How do I secure Firestore data?

A: Implement Firestore security rules enforcing authentication and ownership checks, and validate data before writing.

Q: How do I test this stack?

A: Use Vitest for unit/integration tests and Playwright for end-to-end tests of auth and data flows.

Q: How do I deploy?

A: Build with Nuxt 4 production config, provide env vars, deploy to a Node-capable host, and monitor.