firebase-development

# Firebase Development

## Overview

This skill system guides Firebase development using proven patterns from production projects. It routes to specialized sub-skills based on detected intent.

**Sub-skills:**
- `firebase-development:project-setup` - Initialize new Firebase projects
- `firebase-development:add-feature` - Add functions/collections/endpoints
- `firebase-development:debug` - Troubleshoot emulator and runtime issues
- `firebase-development:validate` - Review Firebase code for security/patterns

## When This Skill Applies

- Starting new Firebase projects
- Adding Cloud Functions or Firestore collections
- Debugging emulator issues or rule violations
- Reviewing Firebase code for security and patterns
- Setting up multi-hosting configurations
- Implementing authentication (API keys or Firebase Auth)

## Routing Logic

### Keywords by Sub-Skill

**project-setup:**
- "new firebase project", "initialize firebase", "firebase init"
- "set up firebase", "create firebase app", "start firebase project"

**add-feature:**
- "add function", "create endpoint", "new tool", "add api"
- "new collection", "add feature", "build", "implement"

**debug:**
- "error", "not working", "debug", "emulator issue"
- "rules failing", "permission denied", "troubleshoot", "deployment failed"

**validate:**
- "review firebase", "check firebase", "validate", "audit firebase"
- "look at firebase code", "security review"

### Routing Process

1. **Analyze Request**: Check for routing keywords
2. **Match Sub-Skill**: Identify best match based on keyword density
3. **Announce**: "I'm using the firebase-development:[sub-skill] skill to [action]"
4. **Route**: Load and execute the sub-skill
5. **Fallback**: If ambiguous, use AskUserQuestion with 4 options

### Fallback Example

If intent is unclear, ask:

```
Question: "What Firebase task are you working on?"
Options:
  - "Project Setup" (Initialize new Firebase project)
  - "Add Feature" (Add functions, collections, endpoints)
  - "Debug Issue" (Troubleshoot errors or problems)
  - "Validate Code" (Review against patterns)
```

## Reference Projects

Patterns are extracted from three production Firebase projects:

| Project | Path | Key Patterns |
|---------|------|--------------|
| **oneonone** | `/Users/dylanr/work/2389/oneonone` | Express API, custom API keys, server-write-only |
| **bot-socialmedia** | `/Users/dylanr/work/2389/bot-socialmedia-server` | Domain-grouped functions, Firebase Auth + roles |
| **meme-rodeo** | `/Users/dylanr/work/2389/meme-rodeo` | Individual function files, entitlements |

## Pattern Summaries

### Multi-Hosting Setup

Three options based on needs:

| Option | When to Use | Key Feature |
|--------|-------------|-------------|
| `site:` based | Multiple independent URLs | Simple, no build coordination |
| `target:` based | Need predeploy hooks | Build scripts run automatically |
| Single + rewrites | Smaller projects | All under one domain |

**Details:** See `docs/examples/multi-hosting-setup.md`

### Authentication

| Pattern | When to Use | Example |
|---------|-------------|---------|
| Custom API keys | MCP tools, server-to-server | oneonone |
| Firebase Auth + roles | User-facing apps | bot-socialmedia |
| Hybrid | Both patterns needed | Web UI + API access |

**Details:** See `docs/examples/api-key-authentication.md`

### Cloud Functions Architecture

| Pattern | When to Use | Structure |
|---------|-------------|-----------|
| Express app | API with middleware, routing | `app.post('/mcp', handler)` |
| Domain-grouped | Feature-rich apps | `posts.ts`, `journal.ts` |
| Individual files | Maximum modularity | One function per file |

**Details:** See `docs/examples/express-function-architecture.md`

### Security Model

| Model | When to Use | Complexity |
|-------|-------------|------------|
| Server-write-only | Light-write apps, high security | Simple rules |
| Client-write + validation | High-volume writes, real-time | Complex rules |

**Strongly prefer server-write-only** for light-write applications.

**Details:** See `docs/examples/firestore-rules-patterns.md`

### Emulator-First Development

Always develop locally with emulators:

```bash
firebase emulators:start
# Access UI at http://127.0.0.1:4000
```

**Key settings in firebase.json:**
- `singleProjectMode: true` - Essential for emulators to work together
- `ui.enabled: true` - Access debug UI

**Details:** See `docs/examples/emulator-workflow.md`

## Modern Tooling Standards

All Firebase projects follow these standards:

| Tool | Purpose | Config File |
|------|---------|-------------|
| TypeScript | Type safety | `tsconfig.json` |
| vitest | Testing | `vitest.config.ts` |
| biome | Linting + formatting | `biome.json` |

### ABOUTME Comment Pattern

Every TypeScript file starts with 2-line ABOUTME comment:

```typescript
// ABOUTME: Brief description of what this file does
// ABOUTME: Second line with additional context
```

### Testing Requirements

- **Unit tests**: Test handlers/utilities in isolation
- **Integration tests**: Test with emulators running
- Both required for every feature

## Common Gotchas

| Issue | Solution |
|-------|----------|
| Emulator ports in use | `lsof -i :5001`, kill process |
| Admin SDK vs Client SDK | Admin bypasses rules, client respects rules |
| Cold start delays | First call takes 5-10s, normal |
| Data persistence | Use Ctrl+C (not kill) to export data |
| CORS in functions | `app.use(cors({ origin: true }))` |

## Summary

This orchestrator routes to specialized sub-skills:

1. Detects intent via keywords
2. Routes to appropriate sub-skill
3. Sub-skills use TodoWrite checklists
4. All reference shared patterns in `docs/examples/`

**Sub-Skills:**
- `firebase-development:project-setup` - Initialize new projects
- `firebase-development:add-feature` - Add functions/collections
- `firebase-development:debug` - Troubleshoot issues
- `firebase-development:validate` - Review code