Cloudflare Pages Deployment¶

This document describes how to deploy the Vite SPA and MkDocs docs to Cloudflare Pages. Adapt as needed for your environment.

This is intentionally high-level and does not include secrets. All keys and tokens should be configured in Cloudflare and Supabase dashboards.

Overview¶

The Workbench AI frontend is a Vite-based single-page app (SPA). It can be deployed to Cloudflare Pages as:

• A static build (npm run build) served from Cloudflare’s CDN.
• An SPA with client-side routing (all non-asset paths rewrite to index.html).

The docs site (docs-site/) is a separate MkDocs project. You can:

• Deploy it as a second Cloudflare Pages project, or
• Use another hosting method (e.g. GitHub Pages, internal docs server).

This page focuses on the SPA; adapt similar concepts for docs.

SPA: Project setup¶

1. In Cloudflare Pages, create a new project from the GitHub repo (anthenkes/workbench-ai).
2. Select the main branch (or your deployment branch).

Build configuration¶

• Framework preset: Vite.
• Build command:

npm install
npm run build

• Build output directory:

dist

If the output directory changes (e.g. via Vite config), update it here.

Environment variables (frontend)¶

Configure these in Cloudflare Pages → Project → Settings → Environment Variables:

• VITE_SUPABASE_URL="https://YOUR_PROJECT_ID.supabase.co"
• VITE_SUPABASE_ANON_KEY="YOUR_SUPABASE_ANON_KEY"

Optionally, any other VITE_* variables used by the app.

Per-environment overriding:

• For preview deployments, use test Supabase projects.
• For production, use the production Supabase project URL + anon key.

SPA: Routing (SPA rewrite)¶

Cloudflare Pages needs to treat the app as a SPA so React Router can handle client-side routes.

Using _redirects¶

Add a file at the root of the built site (or configure equivalent) with:

/*   /index.html   200

This ensures that any non-asset route like /orders, /clients/appointments, or /design/cad-library serves index.html, and React Router handles routing.

Note: The repo includes a vercel.json for Vercel SPA rewrites. For Cloudflare Pages, _redirects plays a similar role.

Docs: MkDocs on Cloudflare Pages (optional)¶

To host the docs on Cloudflare Pages:

1. Create a separate Pages project pointing to the same GitHub repo.
2. Set the root directory to docs-site/.
3. Build command:

pip install mkdocs mkdocs-material mkdocs-mermaid2-plugin
mkdocs build

1. Output directory:

site

You can also choose to host docs elsewhere (e.g. GitHub Pages), as long as the build command and output directory are configured correctly.

Supabase and Stripe configuration¶

Cloudflare Pages hosts the frontend only. All backend logic runs in Supabase and Stripe.

Supabase functions & DB¶

• Edge functions are deployed via Supabase CLI or dashboard (not Cloudflare).
• Environment variables like SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, STRIPE_SECRET_KEY, and STRIPE_WEBHOOK_SECRET are configured in Supabase.

See:

• Supabase Architecture
• Edge Functions Overview

Stripe webhooks¶

• Stripe webhooks point directly to Supabase function URLs (e.g., https://<project>.functions.supabase.co/stripe-webhook).
• Cloudflare does not terminate Stripe webhooks.

Release process (suggested)¶

1. Feature branch

   • Branch off main, do work, add docs.
   • Ensure npm run lint and tests pass.

2. Pull Request

   • Target main (or an integration branch like docs-architecture while iterating).
   • CI can run lint/tests and (optionally) a Vite build and MkDocs build.

3. Preview (optional)

   • Cloudflare Pages runs a preview build for the PR.
   • Verify:
   • Routes work (SPA rewrites).
   • Supabase calls hit the correct dev project.

4. Merge & Production deploy

   • Merge PR into main.
   • Cloudflare Pages builds and deploys to production.

5. Post-deploy checks

   • Smoke test key flows (auth, dashboard, inventory, orders, billing).
   • Check that docs build and links render correctly.

Troubleshooting¶

• White screen / 404 on nested routes

  • Likely missing SPA rewrite. Ensure /* /index.html 200 is configured.

• Supabase auth or data errors

  • Check VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY in Cloudflare Pages config.
  • Confirm the project has all migrations applied.

• Stripe errors

  • Check Supabase edge function logs for stripe-webhook and related functions.
  • Verify STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, and price IDs are configured in Supabase, not in Cloudflare.

Document environment-specific nuances in a private runbook if needed (e.g. QA vs staging vs prod).