Cloudflare Pages Fullstack¶

Status: Authored

A static frontend co-deployed with Cloudflare Pages Functions, usually with same-origin /api/* routes.

Full rubric¶

Cloudflare Pages Fullstack v1

Reference implementation¶

Reference template map¶

What this teaches¶

Choose this stack when one product wants a static frontend and a small API that must share an origin: the same domain, the same deployment, the same release. The point is not that Cloudflare Pages can host functions - it is that co-deploying two halves creates a seam that neither half owns, and almost every failure in this archetype lives in that seam.

The seam has four parts, and this standard exists to make each one explicit. Route ownership: /api/* belongs to Functions, and an SPA router that defines a colliding route silently steals it. Authorization placement: the client guard and the server check look interchangeable in a demo and are not. Environment scope: VITE_* is public by construction while bindings and secrets are per-environment, so preview reusing a production binding is a data incident, not a config nit. Release atomicity: assets and Functions must move as one artifact, or a deploy leaves a frontend calling an API shape that does not exist yet.

Do not choose this stack for a standalone Worker with no static frontend, for a frontend that talks only to somebody else's API (that is React SPA), or when you need a long-running server process. Pages Functions are request-scoped.

Decision matrix¶

Upstream references¶

Cloudflare owns Pages and Functions doctrine; VCQA owns only the seam between the two halves.

• Cloudflare Pages Functions
• Pages Functions routing
• Pages Functions middleware
• Pages Functions bindings
• Vite: env variables and modes
• TSConfig reference
• GitHub Actions secure use
• GitHub Actions deployments and environments
• OWASP Top 10

Scope¶

A static frontend co-deployed with Cloudflare Pages Functions, usually with same-origin /api/* routes.

Not in scope¶

• standalone Workers without Pages
• database-specific D1 migration rules
• generic React component doctrine

Composes¶

• React SPA
• Cloudflare Pages Functions
• TypeScript
• Web Security
• GitHub Actions

VCQA-owned rule surface¶

• same-origin /api seam.
• functions route shape.
• middleware/auth placement.
• bindings and deployed vars.
• SPA/functions deploy assembly.

Detection signals¶

• functions/ directory
• wrangler.toml or Pages project config
• frontend build output deployed with Functions

Combination-born guidelines¶

• SPA routes and Functions routes must not collide; reserve /api/* for Functions.
• Protected API routes need middleware/server-side enforcement, not client-only guards.
• Bindings and secrets are environment-scoped; preview must not reuse production secrets accidentally.

Rule highlights¶

• R-SEAM-1: Reserve the API namespace. Pages Functions own /api/*; the SPA router must not define user-facing routes that shadow that namespace.
• R-SEAM-2: Deep links and API routes are tested together. A deployed preview must prove that unknown UI routes fall back to index.html while API routes still dispatch to Functions.
• R-AUTH-1: Client guards are not authorization. Protected reads and writes require middleware or per-route authorization in Functions.
• R-ENV-1: Client env vars are public. VITE_* values may configure URLs and feature flags, but secrets must live in Cloudflare bindings or deployment secrets.
• R-BIND-1: Bindings are environment-scoped. Preview, staging, and production bindings are named and reviewed separately.
• R-DEPLOY-1: The frontend and Functions deploy as one artifact. The CI pipeline must assemble static assets and Functions into the same Pages deployment.
• R-TYPE-1: API contracts cross the seam. Request/response shapes used by the SPA and Functions should be typed or schema-validated at the boundary.
• R-OBS-1: Server errors are observable. Functions should return safe client errors while preserving enough server-side context for debugging.

Limitations¶

• Route collisions are only provable against a deployed URL. Static analysis can flag a suspicious SPA route, but the authoritative answer comes from a smoke test on a real preview deployment, which a repository scan cannot perform.
• Binding isolation is judged from declared config. If preview and production bindings are configured in the Cloudflare dashboard rather than in version control, the repo cannot show the separation and the check falls back to evidence-only.
• This standard does not own your data layer. D1 schema, migrations, and query safety belong to Cloudflare D1 App; KV and R2 usage patterns are not judged here beyond binding scope.
• It does not own component-level frontend quality. That is React SPA and the cross-cutting rubrics.
• Retained smoke evidence is evidence-only by default. A repo with correct behaviour and no retained transcript scores lower on proof, not on behaviour - the severity escalates only when the missing artifact hides a seam or auth failure.

Anti-patterns¶

• Treating a React route guard as the only protection for private data.
• Putting production secrets in VITE_* variables or checked-in config.
• Letting /api/* be handled by the SPA fallback.
• Deploying frontend assets without the matching Functions version.
• Sharing production bindings with preview deployments.

Benefits¶

• Cloudflare SaaS example app.
• future VCQA fullstack dashboard patterns.

Maintenance¶

Editions are cut on material change, not on a calendar. A review that finds the edition still correct moves Last reviewed forward without a new edition. Metadata lives in standards/registry.json.

Independent Assessment¶

• Cloudflare Pages Fullstack stack page assessment