1# Architecture Patterns
2 
3## Component Resources
4 
5```typescript
6class WorkerApp extends pulumi.ComponentResource {
7    constructor(name: string, args: WorkerAppArgs, opts?) {
8        super("custom:cloudflare:WorkerApp", name, {}, opts);
9        const defaultOpts = {parent: this};
10 
11        this.kv = new cloudflare.WorkersKvNamespace(`${name}-kv`, {accountId: args.accountId, title: `${name}-kv`}, defaultOpts);
12        this.worker = new cloudflare.WorkerScript(`${name}-worker`, {
13            accountId: args.accountId, name: `${name}-worker`, content: args.workerCode,
14            module: true, kvNamespaceBindings: [{name: "KV", namespaceId: this.kv.id}],
15        }, defaultOpts);
16        this.domain = new cloudflare.WorkersDomain(`${name}-domain`, {
17            accountId: args.accountId, hostname: args.domain, service: this.worker.name,
18        }, defaultOpts);
19    }
20}
21```
22 
23## Full-Stack Worker App
24 
25```typescript
26const kv = new cloudflare.WorkersKvNamespace("cache", {accountId, title: "api-cache"});
27const db = new cloudflare.D1Database("db", {accountId, name: "app-database"});
28const bucket = new cloudflare.R2Bucket("assets", {accountId, name: "app-assets"});
29 
30const apiWorker = new cloudflare.WorkerScript("api", {
31    accountId, name: "api-worker", content: fs.readFileSync("./dist/api.js", "utf8"),
32    module: true, kvNamespaceBindings: [{name: "CACHE", namespaceId: kv.id}],
33    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
34    r2BucketBindings: [{name: "ASSETS", bucketName: bucket.name}],
35});
36```
37 
38## Multi-Environment Setup
39 
40```typescript
41const stack = pulumi.getStack();
42const worker = new cloudflare.WorkerScript(`worker-${stack}`, {
43    accountId, name: `my-worker-${stack}`, content: code,
44    plainTextBindings: [{name: "ENVIRONMENT", text: stack}],
45});
46```
47 
48## Queue-Based Processing
49 
50```typescript
51const queue = new cloudflare.Queue("processing-queue", {accountId, name: "image-processing"});
52 
53// Producer: API receives requests
54const apiWorker = new cloudflare.WorkerScript("api", {
55    accountId, name: "api-worker", content: apiCode,
56    queueBindings: [{name: "PROCESSING_QUEUE", queue: queue.id}],
57});
58 
59// Consumer: Process async
60const processorWorker = new cloudflare.WorkerScript("processor", {
61    accountId, name: "processor-worker", content: processorCode,
62    queueConsumers: [{queue: queue.name, maxBatchSize: 10, maxRetries: 3, maxWaitTimeMs: 5000}],
63    r2BucketBindings: [{name: "OUTPUT_BUCKET", bucketName: outputBucket.name}],
64});
65```
66 
67## Microservices with Service Bindings
68 
69```typescript
70const authWorker = new cloudflare.WorkerScript("auth", {accountId, name: "auth-service", content: authCode});
71const apiWorker = new cloudflare.WorkerScript("api", {
72    accountId, name: "api-service", content: apiCode,
73    serviceBindings: [{name: "AUTH", service: authWorker.name}],
74});
75```
76 
77## Event-Driven Architecture
78 
79```typescript
80const eventQueue = new cloudflare.Queue("events", {accountId, name: "event-bus"});
81const producer = new cloudflare.WorkerScript("producer", {
82    accountId, name: "api-producer", content: producerCode,
83    queueBindings: [{name: "EVENTS", queue: eventQueue.id}],
84});
85const consumer = new cloudflare.WorkerScript("consumer", {
86    accountId, name: "email-consumer", content: consumerCode,
87    queueConsumers: [{queue: eventQueue.name, maxBatchSize: 10}],
88});
89```
90 
91## v6.x Versioned Deployments (Blue-Green/Canary)
92 
93```typescript
94const worker = new cloudflare.Worker("api", {accountId, name: "api-worker"});
95const v1 = new cloudflare.WorkerVersion("v1", {accountId, workerId: worker.id, content: fs.readFileSync("./dist/v1.js", "utf8"), compatibilityDate: "2025-01-01"});
96const v2 = new cloudflare.WorkerVersion("v2", {accountId, workerId: worker.id, content: fs.readFileSync("./dist/v2.js", "utf8"), compatibilityDate: "2025-01-01"});
97 
98// Gradual rollout: 10% v2, 90% v1
99const deployment = new cloudflare.WorkersDeployment("canary", {
100    accountId, workerId: worker.id,
101    versions: [{versionId: v2.id, percentage: 10}, {versionId: v1.id, percentage: 90}],
102    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
103});
104```
105 
106**Use:** Canary releases, A/B testing, blue-green. Most apps use `WorkerScript` (auto-versioning).
107 
108## Wrangler.toml Generation (Bridge IaC with Local Dev)
109 
110Generate wrangler.toml from Pulumi config to keep local dev in sync:
111 
112```typescript
113import * as command from "@pulumi/command";
114 
115const workerConfig = {
116    name: "my-worker",
117    compatibilityDate: "2025-01-01",
118    compatibilityFlags: ["nodejs_compat"],
119};
120 
121// Create resources
122const kv = new cloudflare.WorkersKvNamespace("kv", {accountId, title: "my-kv"});
123const db = new cloudflare.D1Database("db", {accountId, name: "my-db"});
124const bucket = new cloudflare.R2Bucket("bucket", {accountId, name: "my-bucket"});
125 
126// Generate wrangler.toml after resources created
127const wranglerGen = new command.local.Command("gen-wrangler", {
128    create: pulumi.interpolate`cat > wrangler.toml <<EOF
129name = "${workerConfig.name}"
130main = "src/index.ts"
131compatibility_date = "${workerConfig.compatibilityDate}"
132compatibility_flags = ${JSON.stringify(workerConfig.compatibilityFlags)}
133 
134[[kv_namespaces]]
135binding = "MY_KV"
136id = "${kv.id}"
137 
138[[d1_databases]]
139binding = "DB"
140database_id = "${db.id}"
141database_name = "${db.name}"
142 
143[[r2_buckets]]
144binding = "MY_BUCKET"
145bucket_name = "${bucket.name}"
146EOF`,
147}, {dependsOn: [kv, db, bucket]});
148 
149// Deploy worker after wrangler.toml generated
150const worker = new cloudflare.WorkerScript("worker", {
151    accountId, name: workerConfig.name, content: code,
152    compatibilityDate: workerConfig.compatibilityDate,
153    compatibilityFlags: workerConfig.compatibilityFlags,
154    kvNamespaceBindings: [{name: "MY_KV", namespaceId: kv.id}],
155    d1DatabaseBindings: [{name: "DB", databaseId: db.id}],
156    r2BucketBindings: [{name: "MY_BUCKET", bucketName: bucket.name}],
157}, {dependsOn: [wranglerGen]});
158```
159 
160**Benefits:**
161- `wrangler dev` uses same bindings as production
162- No config drift between Pulumi and local dev
163- Single source of truth (Pulumi config)
164 
165**Alternative:** Read wrangler.toml in Pulumi (reverse direction) if wrangler is source of truth
166 
167## Build + Deploy Pattern
168 
169```typescript
170import * as command from "@pulumi/command";
171const build = new command.local.Command("build", {create: "npm run build", dir: "./worker"});
172const worker = new cloudflare.WorkerScript("worker", {
173    accountId, name: "my-worker",
174    content: build.stdout.apply(() => fs.readFileSync("./worker/dist/index.js", "utf8")),
175}, {dependsOn: [build]});
176```
177 
178## Content SHA Pattern (Force Updates)
179 
180Prevent false "no changes" detections:
181 
182```typescript
183const version = Date.now().toString();
184const worker = new cloudflare.WorkerScript("worker", {
185    accountId, name: "my-worker", content: code,
186    plainTextBindings: [{name: "VERSION", text: version}], // Forces deployment
187});
188```
189 
190---
191See: [README.md](./README.md), [configuration.md](./configuration.md), [api.md](./api.md), [gotchas.md](./gotchas.md)
192