CLAUDE.md Template: SvelteKit + Firebase Firestore + Firebase Auth + Native Web SDK Sync

Overview

The CLAUDE.md template demonstrates how to bootstrap a SvelteKit application that uses Firebase Firestore for data storage, Firebase Auth for user authentication, and the Native Web SDK Sync for real-time data updates. This copyable template helps developers generate Claude Code blocks tailored to this stack.

Direct answer: This CLAUDE.md Template provides concrete Claude Code instructions for a SvelteKit + Firebase stack, including authentication, data access, and real-time synchronization.

When to Use This CLAUDE.md Template

• Starting a SvelteKit project that uses Firebase Firestore and Auth.
• Prototyping real-time data syncing with Native Web SDK Sync.
• Documenting a repeatable CLAUDE.md block for stack-specific templates.
• Ensuring consistent architecture across SPA routes and data layers.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are a senior frontend architect building a SvelteKit app that uses Firebase Firestore for data storage, Firebase Auth for authentication, and Native Web SDK Sync for real-time data sync.

Architecture rules:
- Use SvelteKit for the UI, with a clear separation between routes, components, and lib.
- Use Firebase modular v9 API (import { initializeApp } from 'firebase/app'; import { getFirestore } from 'firebase/firestore'; import { getAuth } from 'firebase/auth';).
- Do not embed Admin SDK in client code.
- Prefer client-driven data access with server-side protections for privileged operations when needed.

File structure rules:
- src/lib/firebase.ts: Firebase app initialization and config (read from environment vars).
- src/lib/firestore.ts: Firestore wrappers and data access helpers.
- src/lib/auth.ts: Auth helpers (login, logout, session).
- src/routes/**: pages and nested routes using +page.svelte and +layout.svelte.
- .env.local.example: template for development credentials.

Authentication rules:
- Use Firebase Auth with Google and Email/Password; protect routes with route guards.
- Persist user session using default web persistence.

Database rules:
- Firestore rules should require authentication and scope reads/writes to user-specific documents (e.g., doc.data.userId === auth.uid).

Validation rules:
- Validate input on the client; consider server-side guards for privileged operations.

Security rules:
- Never expose API keys in client code.
- Enforce Firestore security rules for all reads/writes.
- Do not bypass security checks on the client.

Testing rules:
- Unit tests for firebase.ts wrappers with mocked Firestore.
- Integration tests for auth flows and data access.
- End-to-end tests for sign-in, data read/write, and realtime sync.

Deployment rules:
- Build with Vite; ensure environment variables are provided in production.
- Validate Firestore rules on deployment.

Things Claude must not do:
- Do not access user credentials; do not bypass security rules; do not hardcode credentials.

Recommended Project Structure

src/
  lib/
    firebase.ts           # Firebase app initialization (web)
    firestore.ts          # Firestore wrapper utilities
    auth.ts               # Auth helpers (login, logout, session)
  routes/
    +layout.svelte
    +page.svelte
  components/
    SignInButton.svelte
  hooks.client.ts
  hooks.server.ts
  app.css

Core Engineering Principles

• Stack cohesion: keep SvelteKit UI separate from Firebase access code.
• Modular design: small, deterministic Claude Code blocks for repeatability.
• Explicit types and named exports to aid code generation and maintainability.
• Security-first: validate data, enforce auth, and minimize privileged client logic.

Code Construction Rules

• Use Firebase modular v9 syntax in all imports.
• Environment-based config; keys should come from process.env, not hardcoded.
• Export named functions from lib modules; avoid default exports for Claude clarity.
• Follow SvelteKit routing conventions: +layout.svelte, +page.svelte, etc.
• Do not import Firebase Admin in client code.
• Document data models and API shapes clearly in lib modules.

Security and Production Rules

• Firestore security rules must enforce auth and per-user access control.
• Use env vars for config; never commit production keys.
• Leverage server endpoints for privileged operations; client should never bypass rules.
• Implement HTTPS, secure cookies, and appropriate CSP in deployment.

Testing Checklist

• Unit tests for firebase.ts wrappers with mocked Firestore.
• Integration tests for authentication flows and data access.
• End-to-end tests for sign-in, CRUD, and realtime sync.
• CI: linting and type-checking for all TS sources.

Common Mistakes to Avoid

• Assuming client-side checks replace server-side security.
• Storing credentials in localStorage beyond session tokens.
• Using Admin privileges from the client.
• Over-fetching data or ignoring realtime sync needs.

FAQ