CLAUDE.md Template: Next.js 16 (Static Export) + Firebase Firestore + Firebase Auth + Firebase SDK Engine

Overview

CLAUDE.md template for a Next.js 16 static export app integrated with Firebase Firestore, Firebase Auth, and the Firebase SDK Engine. This page provides a copyable CLAUDE.md template that developers can paste into CLAUDE.md to guide Claude Code when building and validating the stack.

When to Use This CLAUDE.md Template

• Building a static Next.js 16 site (exported) that relies on client-side Firebase services for authentication and data access.
• Using Firestore as the primary client-side database for reads/writes with proper security and validation.
• Need a concrete, stack-specific CLAUDE.md template with explicit constraints for Claude Code to follow.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role:
- You are Claude Code configured to deliver a production-ready Next.js 16 static-export app with Firebase Firestore, Firebase Auth, and the Firebase SDK Engine. Provide concrete, copyable instructions with verifiable constraints.

Architecture rules:
- Target Next.js 16 with static export (output: export) and a pages-based structure to ensure static HTML where possible.
- Initialize Firebase on the client via the Firebase Web SDK; do not use the Admin SDK in frontend code.
- Do not rely on server-side privileged APIs from the client; prefer client-side Firebase calls or server endpoints with proper authentication.
- Do not embed secrets in the client bundle; fetch config from environment or runtime-provided values.

File structure rules:
- The app is a single Next.js app under web/ with a minimal but complete layout.
- src/firebase/ contains firebaseConfig.js, firebaseAuth.js, and firebaseFirestore.js.
- src/pages/ contains index.jsx and any protected pages using client-side guards.

Authentication rules:
- Use Firebase Client SDK for authentication (Google sign-in, email/password, or other providers).
- Validate sign-in state before rendering protected content.
- Do not store Firebase Admin credentials or service account keys in frontend code.

Database rules:
- Firestore reads/writes occur on the client with proper error handling and user context.
- Implement a thin wrapper module for Firestore interactions to centralize rules and error handling.
- Enforce security rules that require request.auth != null for most data accesses.

Validation rules:
- Validate user input on the client side before sending to Firestore.
- Use simple type checks and avoid trusting unchecked user data.

Security rules:
- Do not expose API keys or service credentials in frontend code.
- Enforce Firestore security rules to require authentication and vendor-approved origins.
- Enable Firebase App Check if available for sensitive environments.

Testing rules:
- Unit tests for firebaseAuth.js and firebaseFirestore.js wrappers with mocked Firebase modules.
- Integration tests for sign-in flows and data read/write using a test project; ensure isolation from production data.
- CI should run lint, type checks, unit tests, and a lightweight integration test suite.

Deployment rules:
- Build and export: npm run build && npm run export.
- Deploy the exported static site to hosting (Firebase Hosting or another static host).
- Do not deploy non-exported code to a static host.

Things Claude must not do:
- Do not use the Firebase Admin SDK in client code.
- Do not embed secrets or private keys in client bundles.
- Do not bypass Firestore security rules or implement insecure shortcuts in the client.
- Do not assume server-side APIs can be trusted without authentication.

Recommended Project Structure

web/
  next.config.js
  package.json
  public/
  src/
    pages/
      index.jsx
      _app.jsx
      protected.jsx
    components/
      Layout.jsx
    firebase/
      firebaseConfig.js
      firebaseAuth.js
      firebaseFirestore.js
    lib/
      api.js

Core Engineering Principles

• Explicitly separate concerns: UI, data access, and auth logic live in dedicated modules.
• Prefer client-side rendering with static export for performance; avoid SSR unless necessary.
• Treat Firebase credentials as secrets; never commit them to source control.
• Guard routes on the client by auth state and enforce Firestore rules on the backend where applicable.
• Maintain idempotent, deterministic code paths for data reads/writes.

Code Construction Rules

• Initialize Firebase with environment-derived config in the client code only.
• Use a centralized Firestore wrapper to enforce consistent error handling and validation.
• All data reads/writes should be through Firebase SDK calls with proper error handling and user feedback.
• Do not perform sensitive operations in client API routes without authentication checks.
• Keep type-safe inputs using basic runtime validation before any Firestore call.

Security and Production Rules

• Firestore security rules require request.auth != null for reads/writes unless a path is explicitly public.
• Do not expose keys or service credentials in frontend code; rely on Firebase App Check and origin validation where possible.
• Enable App Check and set up hosting origin restrictions to prevent misuse.
• Audit dependencies for known vulnerabilities; pin versions and update regularly.

Testing Checklist

• Unit test firebaseAuth.js and firebaseFirestore.js wrappers with mocked Firebase modules.
• Integration tests cover sign-in flow, data retrieval, and writes against a test Firestore instance.
• End-to-end tests simulate user interactions for authentication and data operations.
• CI pipeline runs lint, type checks, unit tests, and a smoke test of export/build.

Common Mistakes to Avoid

• Relying on client-only server secrets or Admin SDK in frontend code.
• Overlooking Firestore Security Rules in favor of client-side bypasses.
• Using static export in a way that requires server-side dynamic data without proper fallback.
• Ignoring environment-based configuration; embedding config directly in code.

FAQ

Q: Can I use Next.js 16 app router with static export for this stack?

A: Yes, but ensure the app uses a pages-based approach or compatible export configuration to generate static HTML where possible.

Q: Should I use Firestore security rules as the only protection?

A: Firestore rules are essential, but also protect data with client checks and minimal privilege on reads/writes.

Q: How do I deploy the static export to hosting?

A: Build the app, run the export, and deploy the output to Firebase Hosting or your chosen static host.

Q: What about sensitive operations?

A: Do not perform privileged operations on the client. Use server-protected endpoints or Cloud Functions with proper auth and verify from the client.