1# Multi-Tenant Patterns
2 
3## Billing by Plan
4 
5```typescript
6interface Env {
7  DISPATCHER: DispatchNamespace;
8  CUSTOMERS_KV: KVNamespace;
9}
10 
11export default {
12  async fetch(request: Request, env: Env): Promise<Response> {
13    const userWorkerName = new URL(request.url).hostname.split(".")[0];
14    const customerPlan = await env.CUSTOMERS_KV.get(userWorkerName);
15    
16    const plans = {
17      enterprise: { cpuMs: 50, subRequests: 50 },
18      pro: { cpuMs: 20, subRequests: 20 },
19      free: { cpuMs: 10, subRequests: 5 },
20    };
21    const limits = plans[customerPlan as keyof typeof plans] || plans.free;
22    
23    const userWorker = env.DISPATCHER.get(userWorkerName, {}, { limits });
24    return await userWorker.fetch(request);
25  },
26};
27```
28 
29## Resource Isolation
30 
31**Complete isolation:** Create unique resources per customer
32- KV namespace per customer
33- D1 database per customer
34- R2 bucket per customer
35 
36```typescript
37const bindings = [{
38  type: "kv_namespace",
39  name: "USER_KV",
40  namespace_id: `customer-${customerId}-kv`
41}];
42```
43 
44## Hostname Routing
45 
46### Wildcard Route (Recommended)
47Configure `*/*` route on SaaS domain → dispatch Worker
48 
49**Benefits:**
50- Supports subdomains + custom vanity domains
51- No per-route limits (regular Workers limited to 100 routes)
52- Programmatic control
53- Works with any DNS proxy settings
54 
55**Setup:**
561. Cloudflare for SaaS custom hostnames
572. Fallback origin (dummy `A 192.0.2.0` if Worker is origin)
583. DNS CNAME to SaaS domain
594. `*/*` route → dispatch Worker
605. Routing logic in dispatch Worker
61 
62```typescript
63export default {
64  async fetch(request: Request, env: Env): Promise<Response> {
65    const hostname = new URL(request.url).hostname;
66    const hostnameData = await env.ROUTING_KV.get(`hostname:${hostname}`, { type: "json" });
67    
68    if (!hostnameData?.workerName) {
69      return new Response("Hostname not configured", { status: 404 });
70    }
71    
72    const userWorker = env.DISPATCHER.get(hostnameData.workerName);
73    return await userWorker.fetch(request);
74  },
75};
76```
77 
78### Subdomain-Only
791. Wildcard DNS: `*.saas.com` → origin
802. Route: `*.saas.com/*` → dispatch Worker
813. Extract subdomain for routing
82 
83### Orange-to-Orange (O2O) Behavior
84 
85When customers use Cloudflare and CNAME to your Workers domain:
86 
87| Scenario | Behavior | Route Pattern |
88|----------|----------|---------------|
89| Customer not on Cloudflare | Standard routing | `*/*` or `*.domain.com/*` |
90| Customer on Cloudflare (proxied CNAME) | Invokes Worker at edge | `*/*` required |
91| Customer on Cloudflare (DNS-only CNAME) | Standard routing | Any route works |
92 
93**Recommendation:** Always use `*/*` wildcard for consistent O2O behavior.
94 
95### Custom Metadata Routing
96 
97For Cloudflare for SaaS: Store worker name in custom hostname `custom_metadata`, retrieve in dispatch worker to route requests. Requires custom hostnames as subdomains of your domain.
98 
99## Observability
100 
101### Logpush
102- Enable on dispatch Worker → captures all user Worker logs
103- Filter by `Outcome` or `Script Name`
104 
105### Tail Workers
106- Real-time logs with custom formatting
107- Receives HTTP status, `console.log()`, exceptions, diagnostics
108 
109### Analytics Engine
110```typescript
111// Track violations
112env.ANALYTICS.writeDataPoint({
113  indexes: [customerName],
114  blobs: ["cpu_limit_exceeded"],
115});
116```
117 
118### GraphQL
119```graphql
120query {
121  viewer {
122    accounts(filter: {accountTag: $accountId}) {
123      workersInvocationsAdaptive(filter: {dispatchNamespaceName: "production"}) {
124        sum { requests errors cpuTime }
125      }
126    }
127  }
128}
129```
130 
131## Use Case Implementations
132 
133### AI Code Execution
134```typescript
135async function deployGeneratedCode(name: string, code: string) {
136  const file = new File([code], `${name}.mjs`, { type: "application/javascript+module" });
137  await client.workersForPlatforms.dispatch.namespaces.scripts.update("production", name, {
138    account_id: accountId,
139    metadata: { main_module: `${name}.mjs`, tags: [name, "ai-generated"] },
140    files: [file],
141  });
142}
143 
144// Short limits for untrusted code
145const userWorker = env.DISPATCHER.get(sessionId, {}, { limits: { cpuMs: 5, subRequests: 3 } });
146```
147 
148**VibeSDK:** For AI-powered code generation + deployment platforms, see [VibeSDK](https://github.com/cloudflare/vibesdk) - handles AI generation, sandbox execution, live preview, and deployment.
149 
150Reference: [AI Vibe Coding Platform Architecture](https://developers.cloudflare.com/reference-architecture/diagrams/ai/ai-vibe-coding-platform/)
151 
152### Edge Functions Platform
153```typescript
154// Route: /customer-id/function-name
155const [customerId, functionName] = new URL(request.url).pathname.split("/").filter(Boolean);
156const workerName = `${customerId}-${functionName}`;
157const userWorker = env.DISPATCHER.get(workerName);
158```
159 
160### Website Builder
161- Deploy static assets + Worker code
162- See [api.md](./api.md#static-assets) for full implementation
163- Salt hashes for asset isolation
164 
165## Best Practices
166 
167### Architecture
168- One namespace per environment (production, staging)
169- Platform logic in dispatch Worker (auth, rate limiting, validation)
170- Isolation automatic (no shared cache, untrusted mode)
171 
172### Routing
173- Use `*/*` wildcard routes
174- Store mappings in KV
175- Handle missing Workers gracefully
176 
177### Limits & Security
178- Set custom limits by plan
179- Track violations with Analytics Engine
180- Use outbound Workers for egress control
181- Sanitize responses
182 
183### Tags
184- Tag all Workers: customer ID, plan, environment
185- Enable bulk operations
186- Filter efficiently
187 
188See [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)
189