diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2277541..95ab4dc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -156,7 +156,7 @@ jobs: du -h dist/* | sort -hr | head -20 - name: Upload build artifacts - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: dist-${{ github.sha }} path: dist/ @@ -177,7 +177,7 @@ jobs: uses: actions/checkout@v4 - name: Download build artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: dist-${{ github.sha }} path: dist/ @@ -221,11 +221,11 @@ jobs: uses: actions/checkout@v4 - name: Download build artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: name: dist-${{ github.sha }} path: dist/ - + - name: Deploy to Vercel (Production) uses: amondnet/vercel-action@v25 with: diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..209e3ef --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +20 diff --git a/README.md b/README.md index 2659a08..ef68824 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ Interact is an enterprise-grade employee engagement platform that transforms wor - [Overview](#overview) - [Documentation](#-documentation) - [Quick Start](#-quick-start) +- [Deploy to Vercel](#-deploy-to-vercel) - [Project Structure](#️-project-structure) - [Current Features](#-current-features) - [Roadmap Highlights](#-roadmap-highlights) @@ -152,7 +153,49 @@ node scripts/generate-prd.js --file ideas/feature.txt - **[docs/SAFE_BRANCH_MERGING.md](./docs/SAFE_BRANCH_MERGING.md)** - Complete guide for safe branch merging - **[docs/PRE_MERGE_CHECKLIST.md](./docs/PRE_MERGE_CHECKLIST.md)** - Checklist template before merging -## 🏗️ Project Structure +## ☁️ Deploy to Vercel + +### One-Click Deploy + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/Krosebrook/interact) + +### Build Settings + +| Setting | Value | +|---------|-------| +| **Framework Preset** | Vite | +| **Build Command** | `npm run build` | +| **Output Directory** | `dist` | +| **Install Command** | `npm ci` | +| **Node.js Version** | 20.x | + +### Required Environment Variables + +Configure these in your Vercel project's **Settings → Environment Variables**: + +| Variable | Description | Required | +|----------|-------------|----------| +| `VITE_BASE44_APP_ID` | Your Base44 application ID | ✅ Yes | +| `VITE_BASE44_BACKEND_URL` | Base44 backend URL (e.g. `https://api.base44.app`) | ✅ Yes | + +### Optional Environment Variables + +| Variable | Description | +|----------|-------------| +| `VITE_GOOGLE_ANALYTICS_ID` | Google Analytics measurement ID | +| `VITE_STRIPE_PUBLISHABLE_KEY` | Stripe publishable key (payments) | +| `VITE_ENABLE_ANALYTICS` | Feature flag: enable analytics (`true`/`false`) | +| `VITE_ENABLE_PWA` | Feature flag: enable PWA (`true`/`false`) | +| `VITE_COMPANY_ID` | Company identifier for multi-tenant setups | + +> **Tip:** Copy `.env.example` to `.env.local` for local development. +> Backend serverless function secrets (OpenAI keys, Cloudinary, etc.) are managed separately in your Base44 dashboard. + +### SPA Routing + +The included `vercel.json` configures a catch-all rewrite so React Router handles all client-side navigation correctly without 404s on page refresh. + + ``` interact/ diff --git a/docs/operations/VERCEL_READINESS_CHECKLIST.md b/docs/operations/VERCEL_READINESS_CHECKLIST.md new file mode 100644 index 0000000..aafd120 --- /dev/null +++ b/docs/operations/VERCEL_READINESS_CHECKLIST.md @@ -0,0 +1,151 @@ +# Vercel Production Readiness Checklist + +A reusable checklist for auditing any Krosebrook repository before deploying to Vercel. + +--- + +## 1. App-Type Detection + +- [ ] Identify the app type: + - **Vercel Web App** – Static site / SPA (React, Vue, Svelte, Vite, Next.js, etc.) + - **Vercel Functions / API** – Serverless API routes only (no frontend build) + - **Monorepo** – Multiple apps/packages in one repo (requires `vercel.json` root config) + - **N/A** – Not a Vercel-deployable project +- [ ] Document the detected framework (Vite, Next.js, CRA, Nuxt, etc.) + +--- + +## 2. Build & Deploy Validation + +- [ ] `npm run build` (or equivalent) completes without errors locally +- [ ] Build output directory exists (`dist/`, `.next/`, `out/`, etc.) +- [ ] No hard-coded `localhost` or development URLs in production code +- [ ] Framework auto-detected by Vercel **or** explicitly set in `vercel.json` + +--- + +## 3. Package Manager & Lockfile + +- [ ] A lockfile is present (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) +- [ ] Lockfile is committed to version control (not in `.gitignore`) +- [ ] Install command matches the lockfile (e.g., `npm ci` for `package-lock.json`) +- [ ] No duplicate lockfiles (only one package manager's lockfile) + +--- + +## 4. package.json Scripts + +- [ ] `build` script is present and produces the expected output +- [ ] `dev` / `start` script is present for local development +- [ ] Scripts use relative paths and are portable (no machine-specific paths) + +--- + +## 5. Node.js Version + +- [ ] `.nvmrc` file present at repo root with the target Node version (e.g., `20`) +- [ ] **or** `engines.node` field in `package.json` (e.g., `"node": ">=20"`) +- [ ] Node version is consistent between local dev, CI, and Vercel +- [ ] Node version is actively supported (see [Node.js releases](https://nodejs.org/en/about/previous-releases)) + +--- + +## 6. vercel.json (only if needed) + +> Add `vercel.json` only when the project requires: monorepo routing, custom rewrites/redirects, +> serverless function configuration, or overriding framework auto-detection. + +- [ ] `"framework"` matches detected framework +- [ ] `"buildCommand"` matches `package.json` build script +- [ ] `"outputDirectory"` matches the actual build output folder +- [ ] `"installCommand"` matches the lockfile (use `npm ci` not `npm install`) +- [ ] SPA fallback rewrite present if using client-side routing: + ```json + { "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] } + ``` +- [ ] No no-op rewrites (e.g., `/api/:path*` → `/api/:path*`) +- [ ] `build.env` references correct environment variable names (no stale names) +- [ ] No `env.NODE_VERSION` (use `.nvmrc` or `engines` instead) +- [ ] Security headers configured (`X-Content-Type-Options`, `X-Frame-Options`, etc.) + +--- + +## 7. Environment Variables + +- [ ] `.env.example` (or `.env.template`) exists and documents all variables +- [ ] All required `VITE_*` (or `NEXT_PUBLIC_*`) variables are listed +- [ ] No real secrets in `.env.example` (use placeholder values like `your_value_here`) +- [ ] `.env.local`, `.env.production`, etc., are in `.gitignore` +- [ ] Required env vars documented in README or deployment docs +- [ ] Vercel project settings include all required env vars for each environment (preview, production) + +--- + +## 8. README – Deploy to Vercel Section + +- [ ] One-click deploy button (Vercel deploy badge) or manual deploy instructions +- [ ] Build command documented +- [ ] Output directory documented +- [ ] Node.js version requirement documented +- [ ] Required environment variables table included +- [ ] Link to `.env.example` for local development setup + +--- + +## 9. GitHub Actions CI + +- [ ] CI workflow exists (`.github/workflows/`) +- [ ] CI runs on `push` to main and on pull requests +- [ ] CI steps include: install → lint → test → build (in that order) +- [ ] All `actions/*` steps use non-deprecated versions (v3 → v4 for artifact actions) +- [ ] Build step uses `npm ci` (not `npm install`) for reproducible installs +- [ ] CI passes on the default branch before deploying + +--- + +## 10. Security + +- [ ] `npm audit --audit-level=high` returns 0 high/critical vulnerabilities +- [ ] No secrets committed to the repository +- [ ] Security headers set in `vercel.json` or middleware +- [ ] Dependencies are up to date (no known CVEs) + +--- + +## 11. SPA Routing (for SPAs only) + +- [ ] All routes fall back to `index.html` (Vercel rewrite or framework config) +- [ ] 404 page configured (optional, improves UX) +- [ ] No hardcoded API base URLs that differ between environments + +--- + +## 12. Final Sign-Off + +- [ ] Production build tested locally with `npm run preview` (Vite) or equivalent +- [ ] Environment variables validated in a Vercel preview deployment +- [ ] No build warnings that indicate missing assets or broken imports +- [ ] Lighthouse / performance score acceptable for production (optional) + +--- + +## Readiness Status Template + +Use this in PR descriptions or deployment tickets: + +``` +### Vercel Readiness Report + +**App Type:** Vercel Web App (React + Vite SPA) +**Detected Framework:** Vite +**Node Version:** 20.x + +#### Blockers Fixed +- [ ] ... + +#### Remaining Blockers +- [ ] ... + +#### Notes +- ... +``` diff --git a/package.json b/package.json index e5f336a..4625814 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,9 @@ "private": true, "version": "0.0.0", "type": "module", + "engines": { + "node": ">=20" + }, "scripts": { "dev": "vite", "build": "vite build", diff --git a/vercel.json b/vercel.json index 52174f6..87ca825 100644 --- a/vercel.json +++ b/vercel.json @@ -5,13 +5,10 @@ "outputDirectory": "dist", "installCommand": "npm ci", "devCommand": "npm run dev", - "env": { - "NODE_VERSION": "20" - }, "build": { "env": { - "VITE_API_URL": "@api_url", - "VITE_BASE44_PROJECT_ID": "@base44_project_id" + "VITE_BASE44_APP_ID": "@vite_base44_app_id", + "VITE_BASE44_BACKEND_URL": "@vite_base44_backend_url" } }, "regions": ["iad1"], @@ -44,8 +41,8 @@ ], "rewrites": [ { - "source": "/api/:path*", - "destination": "/api/:path*" + "source": "/(.*)", + "destination": "/index.html" } ], "redirects": [