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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill files and CLAUDE.md templates to enforce frontend design consistency in production AI workflows.

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.