Workers for Platforms + dispatch namespaces for per-tenant code isolation; best when tenants run untrusted code or you need edge-first compute with D1/KV/DO primitives.
Vercel
Next.js App Router + Middleware for shared-app multi-tenancy; best when tenants share one codebase and you need ISR, React Server Components, and managed deployment.
Pick one; do not mix hosting. The remaining steps apply to both with platform-specific guidance in reference files.
After choosing, load only the references for that platform unless you are explicitly comparing Cloudflare vs Vercel.
Choose domain strategy
Use a dedicated tenant domain (separate from the brand domain) for all subdomains/custom hostnames. Reputation does not isolate; a phishing site on
random.acme.com
damages the whole domain.
Register a separate TLD for tenant workloads (e.g.
acme.app
for tenants,
acme.com
for brand).
Consider PSL for browser cookie isolation; it does not protect reputation. See
psl.md
.
Start PSL submission early; review can take weeks.
Choose tenant identification strategy
Subdomain-based
:
tenant.yourdomain.com
. Requires wildcard DNS. Simplest for many tenants.
Custom domain
Tenant brings own domain, CNAMEs to your platform. Best for serious/paying tenants.
Path-based
:
yourdomain.com/tenant-slug
. No DNS/SSL per tenant, but limits branding and complicates cookie isolation.
Pick one primary strategy; offer custom domain as an upgrade path.
Define isolation model
Cloudflare
Prefer per-tenant Workers for untrusted code (Workers for Platforms dispatch namespaces). Avoid shared-tenant branching unless you fully control code and data.
Vercel
Single shared Next.js app with
tenant_id
scoping. Middleware resolves tenant from hostname; all data queries include tenant context. Use Postgres RLS for defence-in-depth.
Route traffic deterministically
Cloudflare
Platform Worker owns routing; hostname -> tenant id -> dispatch namespace -> tenant Worker. 404 when no mapping exists.
Vercel
Next.js Middleware extracts hostname, rewrites URL to
/domains/[domain]
dynamic segment. Edge Config for sub-millisecond tenant lookups. 404 when no mapping exists.
Tenants never control routing or see each other on either platform.
Pass tenant context through the stack
Cloudflare
Platform Worker resolves tenant and injects headers or bindings before dispatching to tenant Worker.
Vercel
Middleware sets
x-tenant-id
,
x-tenant-slug
,
x-tenant-plan
on forwarded request headers. Server Components read via
headers()
; API routes read from request headers.
Middleware/platform Worker is the single authority; never trust client-supplied tenant identity.
Bind only what is needed
Cloudflare
Least-privilege bindings per tenant (DB/storage/limited platform API), no shared global state. Treat new bindings as explicit changes; redeploy to grant access.
Vercel
Edge Config for tenant config (domain mappings, feature flags, plan info). Vercel SDK (
@vercel/sdk
) for domain management. Database connection scoped by
tenant_id
or database-per-tenant (Neon).
Support custom domains
Provide DNS target, verify ownership, store mapping, and route by hostname.
Cloudflare
Cloudflare for SaaS custom hostnames + managed certs. See
cloudflare-platform.md
.
Vercel
Vercel Domains API via
@vercel/sdk
for programmatic domain CRUD + automatic Let's Encrypt SSL. Wildcard subdomains require Vercel nameservers. See
vercel-domains.md
.
Custom domains shift reputation to the tenant and create natural user segments (casual on platform domain, serious on own domain).
Serve per-tenant static files
robots.txt
,
sitemap.xml
,
llms.txt
must vary by tenant; do not serve from
/public
.
Cloudflare
Generate per-tenant responses in the tenant Worker.
Vercel
Use route handlers per domain segment. See
vercel-platform.md
.
Surface limits as plans
Map platform limits to pricing tiers; expose in API + UI.
Do not run long jobs in requests; use queues/workflows.
See
limits-and-quotas.md
for limits snapshots and source links.
Re-check limits in official docs before final architecture or pricing decisions.
Make the API the product
Everything works over HTTP; UI is for ops/incident/billing.
Platform logic stays in the routing layer (dispatch Worker or Middleware); tenant content serves requests.
If it only works in the UI, the platform is leaking.
Extend without breaking boundaries
Add queues/workflows/containers as optional modes.
Keep routing explicit and isolation intact.
Deliverables
Platform choice rationale: Cloudflare vs Vercel with justification
Tenant identification strategy: subdomain, custom domain, or path-based
Domain map: brand vs tenant domain, PSL plan, custom domain flow
Isolation plan: per-tenant Workers or shared-app with tenant scoping
Routing plan: hostname lookup, dispatch/rewrite logic, fallback behavior
Tenant context flow: how tenant identity propagates through middleware/headers/DB
Binding/config matrix: per-tenant capabilities and data access
Limits-to-pricing map: CPU/memory/request/domain budgets per tier
API surface + ops UI scope
References to load
Always load PSL submission and cookie isolation guidance:
psl.md
If platform is Cloudflare, load platform primitives and routing:
cloudflare-platform.md
If platform is Vercel, load platform primitives and routing:
vercel-platform.md
If platform is Vercel, load domain management and SSL:
vercel-domains.md
Load platform limits and plan mapping last:
limits-and-quotas.md
Pre-commit checklist
Platform chosen with clear rationale documented
Tenant workloads off the brand domain; PSL decision + timeline set
Tenant identification strategy chosen; custom domain upgrade path defined
Isolation model defined: per-tenant Workers (Cloudflare) or shared-app + RLS (Vercel)
Routing authoritative and tenant-blind; dispatch or middleware handles all traffic
Tenant context flows through middleware/platform Worker only; no client-supplied identity trusted
Custom domain onboarding defined with DNS target, verification, and cert provisioning
Per-tenant static files (robots.txt, sitemap.xml) served dynamically
Limits tied to billing; API parity with UI
Limits snapshot refreshed from official docs and dated in planning notes