Setup Next.js project with testing and linting

.eslintignore

@@ -0,0 +1,2 @@
+.next
+node_modules

.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      PLAYWRIGHT_BROWSERS_PATH: ~/.cache/ms-playwright
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+      - run: npm ci
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-pw-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-pw-
+      - run: npx playwright install --with-deps chromium
+      - run: npm run format
+      - run: npm run test
+      - run: npm run test:e2e

.gitignore

@@ -3,7 +3,12 @@
 # dependencies
 /node_modules
 /.pnp
-.pnp.js
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
 
 # testing
 /coverage
@@ -23,14 +28,16 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+.pnpm-debug.log*
 
-# local env files
-.env*.local
-.env
+# env files (can opt-in for committing if needed)
+.env*
 
 # vercel
 .vercel
 
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+src/app/favicon.ico
+test-results/

.prettierignore

@@ -0,0 +1,3 @@
+node_modules
+build
+.next

.prettierrc

@@ -0,0 +1,5 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5"
+}

AGENTS.md

@@ -3,27 +3,32 @@
 This document outlines the step‑by‑step approach for building a Next.js SaaS starter template. The template integrates Stripe billing, Firebase authentication, Shadcn UI components, and Google Pub/Sub streaming for AI responses powered by Gemini. No code is provided here; these are instructions to guide development.
 
 ## 1. Base Setup
+
 1. **Create a new Next.js project** using the App Router (`create-next-app` with `--typescript`).
 2. Enable **React Server Components** in the `/app` directory.
 3. Initialize a git repository and commit the starter template.
 
 ## 2. UI Library
+
 1. Install **Tailwind CSS** via `npx tailwindcss init -p`.
 2. Integrate **Shadcn** components (`npx shadcn-ui@latest init`).
 3. Organize UI components under `/components/ui`.
 
 ## 3. Authentication (Firebase Auth)
+
 1. Create a Firebase project and enable desired auth providers.
 2. Install `firebase` and `firebase-admin` packages.
 3. Configure client-side Firebase in `/lib/firebase/client.ts` and server-side admin in `/lib/firebase/admin.ts`.
 4. Implement authentication hooks and context provider for sign-in/out.
 
 ## 4. Stripe Integration
+
 1. Install `stripe` and `@stripe/stripe-js` packages.
 2. Create server actions or API routes for Stripe checkout and webhook handling.
 3. Manage subscription status in Firestore or your preferred DB.
 
 ## 5. Google Pub/Sub & Gemini API
+
 1. Install `@google-cloud/pubsub` for Pub/Sub communication.
 2. Install `@google/generative-ai` or relevant Gemini SDK.
 3. Create server actions that:
@@ -34,13 +39,15 @@ This document outlines the step‑by‑step approach for building a Next.js SaaS
 4. When Gemini responds, stream data into Pub/Sub instead of returning it directly.
 
 ## 6. API Flow
+
 1. A React Server Component action receives an AI prompt.
 2. The action calls Gemini with an attached system message.
 3. Immediately respond to the client with Pub/Sub connection keys.
 4. On Gemini completion, push tokens/content to Pub/Sub for real-time updates.
 5. Client listens on Pub/Sub to stream results.
 
 ## 7. Project Structure
+
 ```
 /app          - Next.js app router (React Server Components)
 /components   - Shadcn UI components
@@ -49,14 +56,17 @@ This document outlines the step‑by‑step approach for building a Next.js SaaS
 ```
 
 ## 8. Deployment & Environment
+
 1. Store secrets in `.env.local` (Stripe keys, Firebase config, Pub/Sub credentials, Gemini key).
 2. Use a CI/CD solution to deploy (Vercel or your choice).
 
 ## 9. Testing and CI
+
 1. Every feature (auth, billing, Pub/Sub, Gemini integration) should include unit and integration tests.
 2. Use Jest and React Testing Library for frontend components and server actions.
 3. Add API tests to verify Pub/Sub message flow and Stripe webhooks.
 4. Configure a GitHub Actions workflow that installs dependencies and runs all tests on each push and pull request.
 
 ---
+
 Follow these steps to progressively build the SaaS dashboard with real-time AI streaming and Stripe billing.

README.md

@@ -0,0 +1,38 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+
+Run `npm test` for unit tests and `npm run test:e2e` for end-to-end tests.

components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

eslint.config.mjs

@@ -0,0 +1,22 @@
+import { dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { FlatCompat } from '@eslint/eslintrc';
+import prettier from 'eslint-plugin-prettier';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({ baseDirectory: __dirname });
+
+export default [
+  {
+    ignores: ['.next/**', 'node_modules/**'],
+  },
+  ...compat.extends('next/core-web-vitals', 'next/typescript'),
+  {
+    plugins: { prettier },
+    rules: {
+      'prettier/prettier': 'error',
+    },
+  },
+];

next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  /* config options here */
+};
+
+export default nextConfig;