{
  "markdown": "# Firebase + Next.js Template\n\nA template repository for building Next.js applications with Firebase, deployed on Vercel. Includes opinionated tooling for testing, linting, formatting, component development, and CI/CD.\n\n## Stack\n\n| Layer           | Technology                                                                                                              | Purpose                                        |\n| --------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |\n| Framework       | [Next.js](https://nextjs.org/) (App Router)                                                                             | Fullstack React with SSR/API routes            |\n| Language        | TypeScript (strict mode)                                                                                                | Type safety throughout                         |\n| Package Manager | [pnpm](https://pnpm.io/)                                                                                                | Fast, disk-efficient dependency management     |\n| UI Components   | [ShadCN UI](https://ui.shadcn.com/) + [Tailwind CSS](https://tailwindcss.com/)                                          | Composable, accessible component primitives    |\n| State (server)  | [TanStack Query](https://tanstack.com/query)                                                                            | Server state caching, polling, invalidation    |\n| State (client)  | [Redux Toolkit](https://redux-toolkit.js.org/)                                                                          | Local UI state                                 |\n| Database        | [Firebase Realtime Database](https://firebase.google.com/docs/database)                                                 | Persistent storage with real-time push         |\n| Auth            | Firebase Admin SDK (server)                                                                                             | Session-based auth via API routes              |\n| Hosting         | [Vercel](https://vercel.com/)                                                                                           | Deployment, preview URLs, edge functions       |\n| Testing         | [Vitest](https://vitest.dev/) + [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) | Unit, component, and integration tests         |\n| Visual Testing  | [Storybook](https://storybook.js.org/)                                                                                  | Component development and visual documentation |\n| CI/CD           | GitHub Actions                                                                                                          | Lint, format, test, build on every PR          |\n| Monitoring      | [Sentry](https://sentry.io/)                                                                                            | Error tracking (client + server + edge)        |\n\n## Getting Started\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) v24+\n- [pnpm](https://pnpm.io/) v10+\n- A [Firebase project](https://console.firebase.google.com/) with Realtime Database enabled\n- A [Vercel account](https://vercel.com/) (for deployment)\n\n### Create a New Project\n\n1. Click **\"Use this template\"** on GitHub to create a new repository\n2. Clone your new repository\n3. Install dependencies:\n   ```bash\n   pnpm install\n   ```\n4. Copy the environment template and fill in your Firebase credentials:\n   ```bash\n   cp .env.example .env.local\n   ```\n5. Start the development server:\n   ```bash\n   pnpm dev\n   ```\n\n### Environment Variables\n\nSee [`.env.example`](.env.example) for the full list of required and optional environment variables.\n\n## Common Commands\n\n```bash\npnpm dev              # Start dev server\npnpm build            # Production build\npnpm lint             # Lint with ESLint\npnpm format           # Format with Prettier\npnpm format:check     # Check formatting\npnpm test             # Run tests with Vitest\npnpm tsc              # Type check\npnpm storybook        # Start Storybook dev server (port 6006)\npnpm build-storybook  # Build static Storybook\npnpm run env:validate # Validate deployment config files against schema (also runs on every commit)\n```\n\n## Project Structure\n\n```\nproject-root/\n├── src/\n│   ├── app/                    # Next.js App Router pages and API routes\n│   ├── components/\n│   │   ├── ui/                 # ShadCN UI primitives (auto-generated)\n│   │   ├── {feature}/          # Feature-specific components with co-located stories and tests\n│   │   └── {shared}/           # Shared components\n│   ├── lib/\n│   │   ├── firebase/           # Firebase Admin + client SDK wrappers\n│   │   ├── types/              # Core domain types (barrel-exported)\n│   │   └── utils.ts            # Shared utility functions\n│   ├── server/\n│   │   ├── types/              # API response types\n│   │   └── utils/              # Server-only helpers\n│   ├── services/               # Data access layer (Firebase-backed)\n│   ├── hooks/                  # Custom React hooks (barrel-exported)\n│   ├── store/                  # Redux Toolkit slices\n│   └── test-setup/             # Vitest setup files\n├── deployment/\n│   ├── schema.yml              # Allowlist schema for public config keys\n│   ├── environments.yml        # Active environment list\n│   ├── preview.yml             # Public env config for preview (staging)\n│   └── production.yml          # Public env config for production\n├── scripts/\n│   └── validate-config.mjs     # Validates deployment YAMLs against schema\n├── .storybook/                 # Storybook configuration\n├── .github/\n│   ├── actions/setup/          # Composite action: pnpm + Node.js + install\n│   └── workflows/              # CI workflows\n├── docs/                       # Feature documentation\n└── ...config files\n```\n\n## Documentation\n\n- [ARCHITECTURE.md](ARCHITECTURE.md) — Technical decisions, patterns, and infrastructure\n- [AGENTS.md](AGENTS.md) — Code standards and conventions for AI-assisted development\n- [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute to projects built from this template\n\n## Deployment\n\n### Vercel\n\n1. Import your repository in the [Vercel dashboard](https://vercel.com/new)\n2. Add all environment variables from `.env.example`\n3. Deploy — Vercel handles preview deployments on PRs and production deployments on merge to `main`\n\n### Environment Configuration\n\nPublic, 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.\n\nTo change a value, edit the relevant `deployment/{env}.yml` by hand (only `NEXT_PUBLIC_*` / allowlisted keys) and run `pnpm run env:validate`.\n\nLocal 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.\n\n### GitHub Actions\n\nCI runs automatically on every PR with four parallel checks: tests, lint, format, and build. See [`.github/workflows/ci-actions.yml`](.github/workflows/ci-actions.yml).\n\nAdditional workflows:\n\n- **Validate Config** — Validates deployment config against the schema on every PR and push to `main`\n- **Claude Code** — Enables `@claude` mentions in issues and PRs (requires `ANTHROPIC_API_KEY` secret)\n\n## License\n\nMIT\n",
  "bytes": 7780,
  "sha": "d988ceee5a153645a8ff864297416f131238571e796524b4d5a3aed284df44b1",
  "repo_slug": "rmartz/trip-planner",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_rmartz_trip_planner_docs_index_md_f36b3f53/readme"
}