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:

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:

Add first feature → firebase-development:add-feature
Review setup → firebase-development:validate
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

firebase-development:project-setup