Firebase Project Setup

Overview

This sub-skill guides initializing a new Firebase project with proven architecture patterns. It handles Firebase CLI setup, architecture decisions, emulator configuration, and initial project structure.

Key principles:

• Use TypeScript for all functions
• Configure emulators from the start
• Choose architecture patterns early (hosting, auth, functions, security)
• Set up testing infrastructure immediately

When This Sub-Skill Applies

• Starting a brand new Firebase project
• Setting up Firebase for the first time in a repository
• User says: "new firebase project", "initialize firebase", "firebase init", "set up firebase"

Do not use for:

• Adding features to existing projects → firebase-development:add-feature
• Debugging existing setup → firebase-development:debug

Architecture Decisions

Use AskUserQuestion to gather these four decisions upfront:

1. Hosting Configuration

• Single Site - One hosting site, simple project
• Multiple Sites (site:) - Multiple independent URLs
• Multiple with Builds (target:) - Multiple sites with predeploy hooks

Reference: docs/examples/multi-hosting-setup.md

2. Authentication Approach

• API Keys - MCP tools, server-to-server, programmatic access
• Firebase Auth - User-facing app with login UI
• Both - Firebase Auth for web + API keys for tools

Reference: docs/examples/api-key-authentication.md

3. Functions Architecture

• Express API - Many related endpoints, need middleware, RESTful routing
• Domain Grouped - Feature-rich app with distinct areas (posts, admin)
• Individual Files - Independent functions, maximum modularity

Reference: docs/examples/express-function-architecture.md

4. Security Model

• Server-Write-Only (Preferred) - Cloud Functions handle all writes
• Client-Write - High-volume writes, need fastest UX, complex rules

Reference: docs/examples/firestore-rules-patterns.md

TodoWrite Workflow

Create checklist with these 14 steps:

Step 1: Verify Firebase CLI

firebase --version  # Install via npm install -g firebase-tools if missing
firebase login

Step 2: Create Project Directory

mkdir my-firebase-project && cd my-firebase-project
git init && git branch -m main

Create .gitignore with: node_modules/, .env, .env.local, .firebase/, lib/, dist/

Step 3: Run Firebase Init

firebase init

Select: Firestore, Functions, Hosting, Emulators. Choose TypeScript for functions.

Step 4: Gather Architecture Decisions

Use AskUserQuestion for the four decisions above.

Step 5: Configure firebase.json

Set up based on hosting decision. Critical emulator settings:

{
  "emulators": {
    "singleProjectMode": true,
    "ui": { "enabled": true, "port": 4000 }
  }
}

Reference: docs/examples/multi-hosting-setup.md

Step 6: Set Up Functions Structure

Based on architecture choice:

Express: Create middleware/, tools/, services/, shared/ Domain-Grouped: Create shared/types/, shared/validators/ Individual: Create functions/

Install dependencies: express, cors, firebase-admin, firebase-functions, vitest, biome

Step 7: Create Initial Functions Code

Create functions/src/index.ts with ABOUTME comments. Include health check endpoint for Express pattern.

Reference: docs/examples/express-function-architecture.md

Step 8: Configure Firestore Rules

Based on security model decision. Always include:

• Helper functions (isAuthenticated(), isOwner())
• Default deny rule at bottom

Reference: docs/examples/firestore-rules-patterns.md

Step 9: Set Up Testing

Create vitest.config.ts and vitest.emulator.config.ts. Set up __tests__/ and __tests__/emulator/ directories.

Step 10: Configure Biome

Create biome.json with recommended rules. Run npm run lint:fix.

Step 11: Set Up Environment Variables

Create .env.example template. Copy to .env and fill in values.

For hosting: create hosting/.env.local with NEXT_PUBLIC_USE_EMULATORS=true.

Step 12: Initial Git Commit

git add . && git commit -m "feat: initial Firebase project setup"

Step 13: Start Emulators

firebase emulators:start
open http://127.0.0.1:4000

Verify all services start. Test health endpoint if using Express.

Step 14: Create Initial Tests

Create functions/src/__tests__/setup.test.ts with basic verification. Run npm test.

Verification Checklist

Before marking complete:

• [ ] Firebase CLI installed and logged in
• [ ] TypeScript functions compile: npm run build
• [ ] All tests pass: npm test
• [ ] Linting passes: npm run lint
• [ ] Emulators start without errors
• [ ] Emulator UI accessible at http://127.0.0.1:4000
• [ ] Git initialized with commits
• [ ] .env files created and gitignored
• [ ] ABOUTME comments on all files
• [ ] Architecture decisions documented

Project Structures

Express API:

functions/src/
├── index.ts
├── middleware/apiKeyGuard.ts
├── tools/
├── services/
└── __tests__/

Domain-Grouped:

functions/src/
├── index.ts
├── posts.ts
├── users.ts
├── shared/types/
└── __tests__/

Individual Files:

functions/
├── functions/upload.ts
├── functions/process.ts
└── index.js

Next Steps

After setup complete:

1. Add first feature → firebase-development:add-feature
2. Review setup → firebase-development:validate
3. Debug issues → firebase-development:debug

Pattern References

• Hosting: docs/examples/multi-hosting-setup.md
• Auth: docs/examples/api-key-authentication.md
• Functions: docs/examples/express-function-architecture.md
• Rules: docs/examples/firestore-rules-patterns.md
• Emulators: docs/examples/emulator-workflow.md