@donotdev/cli 0.0.16 → 0.0.17

package/templates/root-consumer/guides/dndev/SETUP_VERCEL.md.example

@@ -1,51 +1,39 @@
-# Setup: Vercel
+# Setup: Vercel (Hosting & Functions)
 
-**From zero to deployed: Vercel hosting + API routes with Firebase data layer.**
+**Deploy your frontend (and optionally serverless functions) to Vercel. Works with any backend (Firebase, Supabase, or both).**
 
 ---
 
 ## Architecture
 
-Vercel is your **hosting and API platform** — it serves your frontend and runs serverless API routes.
-Firebase is your **data layer** — Firestore (CRUD), Firebase Auth (users), Firebase Storage (files).
+Vercel serves your built Vite or Next.js app on a global CDN. It can also run **Vercel Functions** (serverless API routes).
 
-The framework generates API routes as Vercel Serverless Functions that talk to Firebase on the backend.
+**Vercel as hosting only** (backend elsewhere):
+- **Firebase** → Cloud Functions + Firestore + Auth + Storage
+- **Supabase** → Edge Functions + PostgreSQL + Auth + Storage
 
----
-
-## Step 1: Create Firebase Project (Data Layer)
-
-Even though you deploy to Vercel, you still need Firebase for data.
-
-1. Go to [Firebase Console](https://console.firebase.google.com) → Create a project
-2. Enable **Authentication** → Email/Password (+ OAuth providers if needed)
-3. Enable **Cloud Firestore** → Create Database → select region
-4. Enable **Storage** if your app uploads files
+**Vercel as hosting + functions** (alongside a backend):
+- Vercel Functions handle API routes (`/api/*`)
+- Combine with Firebase/Supabase for auth + database
 
-Get the Firebase web config from: **Project Settings → General → Your apps → Web app → SDK config**.
+The framework scaffolds `vercel.json` with CSP headers, rewrites, and caching rules.
 
 ---
 
-## Step 2: Run Setup
-
-```bash
-dndev setup firebase
-```
+## Step 1: Create Vercel Project
 
-This writes Firebase SDK config to your app's `.env`. The `overlay-vercel` providers.ts initializes the Firebase client SDK.
+1. Create a [Vercel](https://vercel.com) account
+2. Import your Git repo from the Vercel Dashboard
+3. Set the **Root Directory** to `apps/<your-app>` (or leave blank if monorepo auto-detected)
+4. Set **Framework Preset** to Vite (or Next.js if using Next)
 
 ---
 
-## Step 3: Configure Vercel
+## Step 2: Set Environment Variables
 
-1. Create a [Vercel](https://vercel.com) account and link your Git repo
-2. Import the project in Vercel Dashboard
-3. Set the **Root Directory** to `apps/<your-app>` (or leave blank if monorepo auto-detected)
-4. Set **Framework Preset** to Vite (or Next.js if using Next)
+In Vercel Dashboard → Settings → Environment Variables, copy the env vars from your `apps/<app>/.env`:
 
-**Environment Variables** (in Vercel Dashboard → Settings → Environment Variables):
-
-Copy your Firebase vars from `.env`:
+**If using Firebase:**
 - `VITE_FIREBASE_API_KEY`
 - `VITE_FIREBASE_PROJECT_ID`
 - `VITE_FIREBASE_AUTH_DOMAIN`
@@ -53,81 +41,122 @@ Copy your Firebase vars from `.env`:
 - `VITE_FIREBASE_MESSAGING_SENDER_ID`
 - `VITE_FIREBASE_APP_ID`
 
-For Next.js apps, use `NEXT_PUBLIC_` prefix instead of `VITE_`.
+**If using Supabase:**
+- `VITE_SUPABASE_URL`
+- `VITE_SUPABASE_PUBLIC_KEY`
+
+**Common (all backends):**
+- `VITE_DONOTDEV_LICENSE_KEY`
+- `VITE_STRIPE_PUBLISHABLE_KEY` (if using billing)
+
+**Server-side (Vercel Functions only):**
+- `STRIPE_SECRET_KEY` (if using billing)
+- `SUPABASE_SERVICE_ROLE_KEY` (if using Supabase)
 
-**Server secrets** (for API routes):
-- `STRIPE_SECRET_KEY`
-- `STRIPE_WEBHOOK_SECRET`
-- Any OAuth client secrets
+For Next.js apps, replace the `VITE_` prefix with `NEXT_PUBLIC_` (same var names, different prefix).
 
 ---
 
-## Step 4: API Routes (Functions)
+## Step 3: Deploy
 
-Your backend functions are in `functions/` and deploy as Vercel Serverless Functions.
+**Option A — Git push (recommended)**
+
+Push to your connected branch. Vercel auto-deploys.
 
+```bash
+git push origin main
 ```
-functions/
-├── src/
-│   ├── auth/        # Auth endpoints (signup, login, etc.)
-│   ├── billing/     # Stripe endpoints (checkout, webhook, etc.)
-│   ├── crud/        # CRUD endpoints (create, read, update, delete)
-│   └── oauth/       # OAuth callback handlers
-├── vercel.json      # Route configuration
-├── tsconfig.json
-└── package.json
+
+**Option B — CLI**
+
+```bash
+dndev deploy
 ```
 
-Functions use the Firebase Admin SDK on the server side to access Firestore, verify auth tokens, etc.
+Or directly:
+
+```bash
+bunx vercel --prod
+```
 
 ---
 
-## Step 5: Deploy
+## Vercel Functions (Optional)
 
-**Option A — Git push (recommended)**
+The framework provides helpers for Vercel Functions via `@donotdev/functions/vercel`. Place your API routes in `pages/api/` (Next.js) or `api/` (Vite).
 
-Push to your connected branch. Vercel auto-deploys.
+### Custom Functions
 
-```bash
-git push origin main
+```typescript
+// pages/api/product-details.ts
+import * as v from 'valibot';
+import { createVercelBaseFunction } from '@donotdev/functions/vercel';
+
+const schema = v.object({ productId: v.string() });
+
+export default createVercelBaseFunction(
+  'POST',
+  schema,
+  'get_product_details',
+  async (req, res, data, { uid }) => {
+    // data is validated, uid is the authenticated user
+    const product = await getProduct(data.productId);
+    return res.status(200).json(product);
+  }
+);
 ```
 
-**Option B — Vercel CLI**
+Auth, rate limiting, schema validation, and metrics — all included by default.
 
-```bash
-npx vercel --prod
+### Pre-built Endpoints
+
+The framework ships ready-made API handlers:
+
+```typescript
+// pages/api/auth/claims.ts
+import { setCustomClaims } from '@donotdev/functions/vercel';
+export default setCustomClaims;
+
+// pages/api/billing/checkout.ts
+import { createCheckoutSession } from '@donotdev/functions/vercel';
+import { billingConfig } from '../../../config/billing';
+export default createCheckoutSession(billingConfig);
 ```
 
+Available: auth (claims, status, delete account), billing (checkout, cancel, portal, change plan), OAuth (token exchange, access grants).
+
+### When to use Vercel Functions vs Firebase/Supabase functions
+
+- **Vercel Functions:** API routes, webhooks, third-party proxies — especially in Next.js apps
+- **Firebase Cloud Functions:** Firestore triggers, heavy backend logic tied to Firebase
+- **Supabase Edge Functions:** Database triggers, logic tied to Supabase
+
+**Server secrets** for Vercel Functions go in Vercel Dashboard → Environment Variables (not `VITE_*` or `NEXT_PUBLIC_*` prefixed — those are exposed to the browser).
+
 ---
 
 ## Environment Variables
 
 | File | What Goes Here | Loaded By |
 |------|---------------|-----------|
-| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key | Vite/Next.js (dev + build) |
+| `apps/<app>/.env` | Public keys (backend config, license key, Stripe publishable) | Vite/Next.js (dev + build) |
 | `apps/<app>/.env.local` | Local overrides (gitignored) | Vite/Next.js (overrides .env) |
 | `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
-| `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | API routes runtime |
 | Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
 
 **Client vars** (browser-safe): `VITE_*` or `NEXT_PUBLIC_*` prefix.
-**Server vars** (secrets): No prefix needed in Vercel Dashboard — only accessible in API routes.
 
 ---
 
 ## Local Development
 
 ```bash
-bun dev
+dndev dev
 ```
 
-The app runs locally, talking to your Firebase project. API routes can be tested with:
-
-```bash
-vercel dev
-```
+The app runs locally, talking to your backend (Firebase or Supabase) directly.
 
-Or use Firebase emulators for fully local development:
+For local function emulation:
 
 ```bash
 dndev emu start
@@ -135,42 +164,30 @@ dndev emu start
 
 ---
 
-## Secrets
+## Custom Domain
 
-Server-side secrets go in `functions/.env` locally and in Vercel Dashboard for production.
-
-**We NEVER ask for secret keys.** You place them yourself:
-
-```bash
-# functions/.env
-STRIPE_SECRET_KEY=sk_live_...
-STRIPE_WEBHOOK_SECRET=whsec_...
-```
-
-Then add the same values in Vercel Dashboard → Settings → Environment Variables.
-
-See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+1. Vercel Dashboard → Settings → Domains
+2. Add your domain
+3. Update DNS records as instructed by Vercel
+4. If using Firebase Auth: update your `FIREBASE_AUTH_DOMAIN` env var to your custom domain
 
 ---
 
 ## Troubleshooting
 
-**"Firebase config not loading"**
-→ Check `.env` is in your **app directory** (`apps/<app>/.env`), not repo root
-→ Vite vars must start with `VITE_`, Next.js vars with `NEXT_PUBLIC_`
-
-**"401 / Permission denied on API routes"**
-→ Check Firebase service account key is configured in Vercel env vars
-→ Verify `GOOGLE_APPLICATION_CREDENTIALS` or inline credentials in API routes
+**"Build fails on Vercel"**
+→ Check Root Directory is set to your app directory
+→ Ensure `package.json` has correct `build` script
+→ Check all `VITE_*` env vars are set in Vercel Dashboard
 
 **"CORS error"**
 → Vercel handles CORS for same-origin requests automatically
-→ For cross-origin: add CORS headers in your API route handler
+→ For cross-origin: CSP headers in `vercel.json` are pre-configured for your backend
 
-**"Build fails on Vercel"**
-→ Check Root Directory is set to your app directory
-→ Ensure `package.json` has correct `build` script
+**".env values not loading"**
+→ Vercel only reads env vars from its Dashboard, not from `.env` files
+→ Make sure all required vars are set in Vercel Dashboard → Environment Variables
 
 ---
 
-**`dndev setup firebase` → configure Vercel project → set env vars → `git push`. Vercel deploys automatically.**
+**Import repo in Vercel → set env vars → `git push`. Vercel deploys automatically.**

package/templates/root-consumer/guides/dndev/advanced/EMULATORS.md.example

@@ -10,7 +10,7 @@ The DoNotDev framework uses a strict separation between local development and pr
 
 **`.env.local` is the exclusive source of truth for emulators.** 
 
-When you run `dn emu <app-name>`, the framework loads environment variables **ONLY** from `functions/.env.local`.
+When you run `dndev emu <app-name>`, the framework loads environment variables **ONLY** from `functions/.env.local`.
 
 1. Create `functions/.env.local` (it is git-ignored by default).
 2. Add your local development keys (e.g., Stripe ephemeral webhook secret).
@@ -25,7 +25,7 @@ STRIPE_WEBHOOK_SECRET=whsec_... # Get this from 'stripe listen' output
 
 **`.env` is the source of truth for production secrets.**
 
-These are the secrets that will be synced to Firebase Cloud Functions when you run `dn deploy` or `dn sync-secrets`.
+These are the secrets that will be synced to Firebase Cloud Functions when you run `dndev deploy` or `dndev sync-secrets`.
 
 ```bash
 # functions/.env

package/dist/bin/commands/firebase-setup.d.ts

@@ -1,6 +0,0 @@
-/**
- * @fileoverview Firebase Setup Command Wrapper
- * @description Re-exports firebaseSetup from tooling for CLI bundling.
- */
-export { firebaseSetup as main } from '@donotdev/tooling';
-//# sourceMappingURL=firebase-setup.d.ts.map

package/dist/bin/commands/firebase-setup.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"firebase-setup.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/firebase-setup.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/firebase-setup.js

@@ -1,7 +0,0 @@
-// packages/cli/src/bin/commands/firebase-setup.ts
-/**
- * @fileoverview Firebase Setup Command Wrapper
- * @description Re-exports firebaseSetup from tooling for CLI bundling.
- */
-export { firebaseSetup as main } from '@donotdev/tooling';
-//# sourceMappingURL=firebase-setup.js.map

package/dist/bin/commands/firebase-setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"firebase-setup.js","sourceRoot":"","sources":["../../../src/bin/commands/firebase-setup.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/supabase-setup.d.ts

@@ -1,6 +0,0 @@
-/**
- * @fileoverview Supabase Setup Command Wrapper
- * @description Re-exports supabaseSetup from tooling for CLI bundling.
- */
-export { supabaseSetup as main } from '@donotdev/tooling';
-//# sourceMappingURL=supabase-setup.d.ts.map

package/dist/bin/commands/supabase-setup.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"supabase-setup.d.ts","sourceRoot":"","sources":["../../../src/bin/commands/supabase-setup.ts"],"names":[],"mappings":"AACA;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/bin/commands/supabase-setup.js

@@ -1,7 +0,0 @@
-// packages/cli/src/bin/commands/supabase-setup.ts
-/**
- * @fileoverview Supabase Setup Command Wrapper
- * @description Re-exports supabaseSetup from tooling for CLI bundling.
- */
-export { supabaseSetup as main } from '@donotdev/tooling';
-//# sourceMappingURL=supabase-setup.js.map

package/dist/bin/commands/supabase-setup.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"supabase-setup.js","sourceRoot":"","sources":["../../../src/bin/commands/supabase-setup.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD;;;GAGG;AAEH,OAAO,EAAE,aAAa,IAAI,IAAI,EAAE,MAAM,mBAAmB,CAAC"}