clover's git

the-knife

1	---
2	title: Custom domains & routes
3	description: Serve Workers from your own domain — create or adopt a Zone, attach custom domains, route hostname patterns, manage DNS records, and control the workers.dev subdomain.
4	sidebar:
5	order: 0
6	---
7
8	Every Worker gets a `workers.dev` URL by default, but production apps
9	live on their own domain. This guide covers the pieces involved: the
10	Zone that holds your domain, the `domain` prop that attaches hostnames
11	to a Worker, Routes for pattern-based dispatch, plain DNS records, and
12	the account's `workers.dev` subdomain.
13
14	All the snippets below run inside a Stack's `Effect.gen` body:
15
16	```typescript
17	// alchemy.run.ts
18	import * as Alchemy from "alchemy";
19	import * as Cloudflare from "alchemy/Cloudflare";
20	import * as Effect from "effect/Effect";
21
22	export default Alchemy.Stack(
23	"MyApp",
24	{ providers: Cloudflare.providers(), state: Cloudflare.state() },
25	Effect.gen(function* () {
26	// resources go here
27	return {};
28	}),
29	);
30	```
31
32	## Create a Zone
33
34	A Zone is a domain managed by Cloudflare. Declaring one gives you the
35	zone's identifiers and the name servers to point your registrar at:
36
37	```typescript
38	const zone = yield* Cloudflare.Zone.Zone("MyZone", {
39	name: "example.com",
40	});
41	// zone.zoneId, zone.nameServers, zone.accountId, zone.status, ...
42	```
43
44	Zones default to **retain** on removal — destroying the stack does NOT
45	delete the zone in Cloudflare. Opt in to actual deletion by wrapping
46	the resource in `destroy()` from `alchemy/RemovalPolicy`:
47
48	```typescript
49	import { destroy } from "alchemy/RemovalPolicy";
50
51	const zone = yield* Cloudflare.Zone.Zone("MyZone", {
52	name: "example.com",
53	}).pipe(destroy());
54	```
55
56	## Adopt an existing Zone
57
58	Most domains already exist in Cloudflare before Alchemy enters the
59	picture. A zone carries no ownership markers, so the engine refuses to
60	take over a pre-existing zone unless you opt in with `adopt(true)`:
61
62	```typescript
63	import { adopt } from "alchemy/AdoptPolicy";
64
65	const zone = yield* Cloudflare.Zone.Zone("MyZone", {
66	name: "example.com",
67	}).pipe(adopt(true));
68	```
69
70	Without `adopt(true)`, deploying against an existing zone fails with a
71	typed `OwnedBySomeoneElse` error instead of silently clobbering it.
72	Once adopted, the zone behaves like any other managed resource — and it
73	still retains on destroy unless you add `destroy()`.
74
75	## Attach a custom domain to a Worker
76
77	Pass `domain` — Cloudflare provisions the DNS record and certificate;
78	the zone is inferred from the hostname and must already exist in the
79	account:
80
81	```typescript
82	const worker = yield* Cloudflare.Worker("Api", {
83	main: "./src/api.ts",
84	domain: "api.example.com",
85	});
86	// worker.url === "https://api.example.com"
87	```
88
89	`aliases` also serve the Worker; `redirects` answer with a 301 (path
90	and query preserved) to the canonical name, before the Worker runs —
91	ideal for domain migrations:
92
93	```typescript
94	const worker = yield* Cloudflare.Worker("Api", {
95	main: "./src/api.ts",
96	domain: {
97	name: "api.example.com",
98	aliases: ["api-v2.example.com"],
99	redirects: ["api.old-example.com"], // 301 → https://api.example.com
100	},
101	workersDev: false,
102	});
103	// worker.url === "https://api.example.com"
104	// worker.urls === ["https://api.example.com", "https://api-v2.example.com"]
105	// worker.domain === { name: "api.example.com",
106	// aliases: ["api-v2.example.com"],
107	// redirects: ["api.old-example.com"] }
108	```
109
110	The canonical domain leads `worker.urls` (ahead of `workers.dev`), and
111	redirect hostnames never appear there — they serve no content. Their
112	redirect rules live in the zone's `http_request_dynamic_redirect`
113	phase, which runs before Workers.
114
115	Set `previews: true` so [Worker Previews](/cloudflare/compute/previews)
116	of this Worker are served at `<preview-name>.api.example.com`. That is
117	a parent setting — enable it on the production Worker, not on the
118	Preview Worker. Use a dedicated hostname (`previews.example.com`) if
119	production already has subdomains, so the wildcard does not collide.
120
121	## Route a hostname pattern to a Worker
122
123	Routes are the classic alternative: a zone-level mapping from a URL
124	pattern to a Worker script. Unlike the `domain` prop, a route can match
125	paths (`example.com/api/*`), so different Workers can serve different
126	parts of one hostname:
127
128	```typescript
129	const worker = yield* Cloudflare.Worker("Api", {
130	main: "./src/api.ts",
131	});
132
133	yield* Cloudflare.Workers.WorkerRoute("ApiRoute", {
134	zoneId: zone.zoneId,
135	pattern: "api.example.com/*",
136	script: worker.workerName,
137	});
138	```
139
140	A route only fires on hostnames that resolve through Cloudflare's
141	proxy, so pair it with a proxied DNS record. When the Worker is the
142	only origin, an `AAAA 100::` placeholder is the conventional choice:
143
144	```typescript
145	yield* Cloudflare.DNS.Record("ApiPlaceholder", {
146	zoneId: zone.zoneId,
147	name: "api.example.com",
148	type: "AAAA",
149	content: "100::",
150	proxied: true,
151	});
152	```
153
154	Cloudflare enforces one route per pattern per zone, and routes carry no
155	ownership markers — so if the route already exists, Alchemy reports it
156	as unowned and refuses to take it over unless you opt in with
157	`adopt(true)` (the same policy as zones):
158
159	```typescript
160	import { adopt } from "alchemy/AdoptPolicy";
161
162	yield* Cloudflare.Workers.WorkerRoute("ApiRoute", {
163	zoneId: zone.zoneId,
164	pattern: "api.example.com/*",
165	script: worker.workerName,
166	}).pipe(adopt(true));
167	```
168
169	Both `pattern` and `script` are mutable — changing either updates the
170	same physical route in place. Changing `zoneId` triggers a replacement.
171
172	## DNS records for non-Worker targets
173
174	Not everything on your zone is a Worker. `Cloudflare.DNS.Record`
175	manages individual records — here a plain A record pointing at an
176	external server:
177
178	```typescript
179	yield* Cloudflare.DNS.Record("ApiA", {
180	zoneId: zone.zoneId,
181	name: "api.example.com",
182	type: "A",
183	content: "203.0.113.42",
184	ttl: 300,
185	});
186	```
187
188	Proxied records (orange-clouded) route through Cloudflare's edge —
189	`proxied: true` is only valid for `A`, `AAAA`, and `CNAME` records, and
190	requires the automatic TTL. A common shape is a proxied CNAME at a
191	Cloudflare Tunnel:
192
193	```typescript
194	yield* Cloudflare.DNS.Record("AdminCname", {
195	zoneId: zone.zoneId,
196	name: "cluster-admin.example.com",
197	type: "CNAME",
198	content: `${tunnel.tunnelId}.cfargotunnel.com`,
199	proxied: true,
200	});
201	```
202
203	DNS records get the same adoption safety as routes: if a record with
204	the same `(name, type)` already exists in the zone, Alchemy reports it
205	as unowned and requires `adopt(true)` to take it over. This protects
206	hand-edited records — especially apex `A`/`AAAA` and email
207	DKIM/SPF records the dashboard often manages — from being clobbered.
208
209	## Disable Workers on a path
210
211	A route with no `script` opts matching requests out of Workers
212	entirely. Use it to punch a hole in a broader wildcard route — for
213	example, letting `/assets/*` bypass the Worker and hit the origin
214	directly:
215
216	```typescript
217	yield* Cloudflare.Workers.WorkerRoute("AssetsBypass", {
218	zoneId: zone.zoneId,
219	pattern: "example.com/assets/*",
220	});
221	```
222
223	## Control the workers.dev subdomain
224
225	Per Worker, the `workersDev` prop toggles the `workers.dev` URLs (it
226	defaults to `true`). Once a custom domain serves production traffic,
227	you may want to switch them off — the custom domain then becomes
228	`worker.url`:
229
230	```typescript
231	const worker = yield* Cloudflare.Worker("Api", {
232	main: "./src/api.ts",
233	domain: "api.example.com",
234	workersDev: false,
235	});
236	// worker.url === "https://api.example.com"
237	```
238
239	The object form controls the stable URL and per-version preview URLs
240	independently. With the stable URL off and previews on, each deploy's
241	preview URL (`https://<version-prefix>-<name>.<subdomain>.workers.dev`)
242	becomes `worker.url`:
243
244	```typescript
245	const worker = yield* Cloudflare.Worker("Api", {
246	main: "./src/api.ts",
247	workersDev: { enabled: false, previewsEnabled: true },
248	});
249	```
250
251	Account-wide, the `<subdomain>` in
252	`https://<script>.<subdomain>.workers.dev` is a singleton you can pin
253	with the `Subdomain` resource:
254
255	```typescript
256	const sub = yield* Cloudflare.Workers.Subdomain("Subdomain", {
257	subdomain: "my-team",
258	});
259	// Workers are now served from https://<script>.my-team.workers.dev
260	```
261
262	Subdomain names are globally unique across all Cloudflare accounts;
263	claiming a taken name fails with a typed `SubdomainAlreadyExists`
264	error. Destroy is capture-and-restore: the subdomain is renamed back to
265	whatever the account had before Alchemy first managed it.
266
267	:::caution
268	Renaming the subdomain immediately changes the URL of **every**
269	deployed Worker on the account that relies on `workers.dev`. Only
270	manage this resource on accounts where that is acceptable.
271	:::
272
273	## Where next
274
275	- [Domains & DNS](/cloudflare/networking/domains) — the full domain-management
276	surface: zone settings, DNSSEC, certificates, and more.
277	- [Workers](/cloudflare/compute/workers) — the Worker resource itself and its
278	binding system.
279
280	Reference:
281
282	- [Zone API reference](/providers/cloudflare/zone/zone)
283	- [WorkerRoute API reference](/providers/cloudflare/workers/workerroute)
284	- [Record API reference](/providers/cloudflare/dns/record)
285	- [Subdomain API reference](/providers/cloudflare/workers/subdomain)