Firebase + Next.js Template

A template repository for building Next.js applications with Firebase, deployed on Vercel. Includes opinionated tooling for testing, linting, formatting, component development, and CI/CD.

Stack

Layer	Technology	Purpose
Framework	Next.js (App Router)	Fullstack React with SSR/API routes
Language	TypeScript (strict mode)	Type safety throughout
Package Manager	pnpm	Fast, disk-efficient dependency management
UI Components	ShadCN UI + Tailwind CSS	Composable, accessible component primitives
State (server)	TanStack Query	Server state caching, polling, invalidation
State (client)	Redux Toolkit	Local UI state
Database	Firebase Realtime Database	Persistent storage with real-time push
Auth	Firebase Admin SDK (server)	Session-based auth via API routes
Hosting	Vercel	Deployment, preview URLs, edge functions
Testing	Vitest + @testing-library/react	Unit, component, and integration tests
Visual Testing	Storybook	Component development and visual documentation
CI/CD	GitHub Actions	Lint, format, test, build on every PR
Monitoring	Sentry	Error tracking (client + server + edge)

Getting Started

Prerequisites

• Node.js v24+
• pnpm v10+
• A Firebase project with Realtime Database enabled
• A Vercel account (for deployment)

Create a New Project

1. Click "Use this template" on GitHub to create a new repository
2. Clone your new repository
3. Install dependencies:

   pnpm install
   

4. Copy the environment template and fill in your Firebase credentials:

   cp .env.example .env.local
   

5. Start the development server:

   pnpm dev
   

Environment Variables

See .env.example for the full list of required and optional environment variables.

Common Commands

pnpm dev              # Start dev server
pnpm build            # Production build
pnpm lint             # Lint with ESLint
pnpm format           # Format with Prettier
pnpm format:check     # Check formatting
pnpm test             # Run tests with Vitest
pnpm tsc              # Type check
pnpm storybook        # Start Storybook dev server (port 6006)
pnpm build-storybook  # Build static Storybook
pnpm run env:validate # Validate deployment config files against schema (also runs on every commit)

Project Structure

project-root/
├── src/
│   ├── app/                    # Next.js App Router pages and API routes
│   ├── components/
│   │   ├── ui/                 # ShadCN UI primitives (auto-generated)
│   │   ├── {feature}/          # Feature-specific components with co-located stories and tests
│   │   └── {shared}/           # Shared components
│   ├── lib/
│   │   ├── firebase/           # Firebase Admin + client SDK wrappers
│   │   ├── types/              # Core domain types (barrel-exported)
│   │   └── utils.ts            # Shared utility functions
│   ├── server/
│   │   ├── types/              # API response types
│   │   └── utils/              # Server-only helpers
│   ├── services/               # Data access layer (Firebase-backed)
│   ├── hooks/                  # Custom React hooks (barrel-exported)
│   ├── store/                  # Redux Toolkit slices
│   └── test-setup/             # Vitest setup files
├── deployment/
│   ├── schema.yml              # Allowlist schema for public config keys
│   ├── environments.yml        # Active environment list
│   ├── preview.yml             # Public env config for preview (staging)
│   └── production.yml          # Public env config for production
├── scripts/
│   └── validate-config.mjs     # Validates deployment YAMLs against schema
├── .storybook/                 # Storybook configuration
├── .github/
│   ├── actions/setup/          # Composite action: pnpm + Node.js + install
│   └── workflows/              # CI workflows
├── docs/                       # Feature documentation
└── ...config files

Documentation

• ARCHITECTURE.md — Technical decisions, patterns, and infrastructure
• AGENTS.md — Code standards and conventions for AI-assisted development
• CONTRIBUTING.md — How to contribute to projects built from this template

Deployment

Vercel

1. Import your repository in the Vercel dashboard
2. Add all environment variables from .env.example
3. Deploy — Vercel handles production deployments on merge to main. Preview deployments are label-gated: a preview is built (by .github/workflows/preview-deploy.yml, a caller of the shared rmartz/vercel-preview-ci workflow) only while a PR carries UAT ready, not on every push. vercel.json's git.deploymentEnabled turns off Vercel's own preview builds

Environment Configuration

Public, non-secret environment config (Firebase project IDs, Sentry org/project, NEXT_PUBLIC_* keys) lives in deployment/{env}.yml and is validated against deployment/schema.yml on every commit and in CI. Secrets never go in these files.

To change a value, edit the relevant deployment/{env}.yml by hand (only NEXT_PUBLIC_* / allowlisted keys) and run pnpm run env:validate.

Local tooling to push config to Vercel and rotate secrets is being replaced by the planned envctl CLI. The former update-config.sh / deploy-config.sh / rotate-keys.sh helpers were removed when vercel-deploy-scripts (which transitively supplied the vercel CLI they used) was dropped; until envctl lands, push and secret rotation are done manually via the Vercel dashboard/CLI.

GitHub Actions

CI runs automatically on every PR with four parallel checks: tests, lint, format, and build. See .github/workflows/ci-actions.yml.

Additional workflows:

• Validate Config — Validates deployment config against the schema on every PR and push to main
• Claude Code — Enables @claude mentions in issues and PRs (requires ANTHROPIC_API_KEY secret)

License

MIT