The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: DNS Adapters |
| 3 | description: Publish a custom domain's DNS records in Route 53, Cloudflare, or Hetzner DNS from any platform, and build an adapter for another DNS host. |
| 4 | --- |
| 5 | |
| 6 | A custom domain has two parts. The platform that **serves** the hostname |
| 7 | (CloudFront, a load balancer, API Gateway, a Worker, a Fly App) issues or |
| 8 | attaches a certificate and tells you which DNS records it needs. The DNS |
| 9 | host that **publishes** the hostname's records is often somewhere else: |
| 10 | a domain registered with Cloudflare Registrar can point at an AWS website, |
| 11 | and a Route 53 zone can point at a Fly App. |
| 12 | |
| 13 | A DNS adapter connects the two. Set `domain.dns` to the DNS host, and the |
| 14 | platform publishes its certificate-validation records and the records that |
| 15 | point the hostname at it through that host: |
| 16 | |
| 17 | ```typescript |
| 18 | yield* AWS.Website.StaticSite("Site", { |
| 19 | path: "./dist", |
| 20 | domain: { |
| 21 | name: "app.example.com", |
| 22 | dns: Cloudflare.DNS.Adapter(), |
| 23 | }, |
| 24 | }); |
| 25 | ``` |
| 26 | |
| 27 | The stack's `providers` must include the DNS host's `providers()` layer |
| 28 | alongside the platform's, here `Layer.mergeAll(AWS.providers(), |
| 29 | Cloudflare.providers())`. |
| 30 | |
| 31 | ## Built-in adapters |
| 32 | |
| 33 | | Adapter | DNS host | Options | |
| 34 | | --- | --- | --- | |
| 35 | | `Cloudflare.DNS.Adapter()` | A Cloudflare zone | `zone` (zone id, zone name, or `Zone` resource), `proxied` | |
| 36 | | `AWS.Route53.Adapter()` | A Route 53 hosted zone | `hostedZoneId` | |
| 37 | | `Hetzner.DNS.Adapter()` | A Hetzner DNS zone | `zone` (zone id, zone name, or `Hetzner.Zone` resource) | |
| 38 | |
| 39 | Each adapter infers the zone from every hostname by walking its parent |
| 40 | domains. Pass `zone` (or `hostedZoneId`) to pin it. |
| 41 | |
| 42 | `Cloudflare.DNS.Adapter({ proxied: true })` sends the alias records through |
| 43 | Cloudflare's proxy. Validation and verification records are always |
| 44 | DNS-only. Cloudflare flattens a `CNAME` at the zone apex; Route 53 and |
| 45 | Hetzner can't, so an apex hostname on those hosts needs an AWS alias target |
| 46 | (Route 53) or an address target. |
| 47 | |
| 48 | ## Where `dns` works |
| 49 | |
| 50 | | Platform | `dns` omitted | Records published through the adapter | |
| 51 | | --- | --- | --- | |
| 52 | | `AWS.Website.*` sites and `AWS.Website.Router` | Route 53 | ACM validation `CNAME`s; each hostname aliased to CloudFront | |
| 53 | | `AWS.ECS.Service` load balancer `domain` | Route 53 | ACM validation `CNAME`s; each hostname aliased to the load balancer | |
| 54 | | `AWS.Lambda.Function` `domain` | Route 53 | ACM validation `CNAME`s; each hostname aliased to its API Gateway domain | |
| 55 | | `Cloudflare.Worker` and `Cloudflare.Website.*` | Native Worker custom domain | Custom-hostname ownership and certificate `TXT` records; a `CNAME` to your Cloudflare for SaaS zone | |
| 56 | | `Fly.Website.*` | You publish the records | The ACME challenge `CNAME`; `A`/`AAAA` records at the site | |
| 57 | | `Railway.Website.*` | You publish the records | The `CNAME` and verification `TXT` Railway requires | |
| 58 | | `Neon.Website.*` | You publish the records | A `CNAME` to the custom domain's target | |
| 59 | | `Prisma.Website.*` | You publish the records | A `CNAME` to the app's regional switchboard, published before the domain is registered | |
| 60 | | `Hetzner.Website.*` | An `A` record in `zone` | An `A` record at the server | |
| 61 | |
| 62 | A plain string `domain` keeps each platform's default. Setting `dns` never |
| 63 | changes how the platform serves the hostname, only where its records live. |
| 64 | |
| 65 | ### AWS websites and load balancers |
| 66 | |
| 67 | `dns` sits next to the other `domain` fields: |
| 68 | |
| 69 | ```typescript |
| 70 | const router = yield* AWS.Website.Router("Router", { |
| 71 | domain: { |
| 72 | name: "example.com", |
| 73 | aliases: ["www.example.com"], |
| 74 | dns: Cloudflare.DNS.Adapter({ zone: "example.com" }), |
| 75 | }, |
| 76 | }); |
| 77 | ``` |
| 78 | |
| 79 | ACM still issues the certificate. With Route 53 the certificate resource |
| 80 | publishes its own validation records. With any other host the composite |
| 81 | requests the certificate with `dnsValidation: "external"`, publishes the |
| 82 | validation `CNAME`s through the adapter, and waits for issuance with |
| 83 | `AWS.ACM.CertificateValidation` before CloudFront or the listener uses it. |
| 84 | Hostnames that sites attached to a `Router` bind onto its record set go |
| 85 | through the same adapter. |
| 86 | |
| 87 | `AWS.ECS.Service` takes the same field on its load balancer domain: |
| 88 | |
| 89 | ```typescript |
| 90 | yield* AWS.ECS.Service("Api", { |
| 91 | cluster, |
| 92 | image: "my-org/api:latest", |
| 93 | port: 3000, |
| 94 | loadBalancer: { |
| 95 | domain: { name: "api.example.com", dns: Cloudflare.DNS.Adapter() }, |
| 96 | }, |
| 97 | }); |
| 98 | ``` |
| 99 | |
| 100 | ### Lambda Functions |
| 101 | |
| 102 | Function URLs can't serve a custom hostname, so a Function's `domain` |
| 103 | composes an API Gateway v2 HTTP API in front of it, with a regional ACM |
| 104 | certificate and an API Gateway domain name per hostname. The HTTP API uses |
| 105 | payload format 2.0, the same event shape as a Function URL, so a `fetch` |
| 106 | handler works unchanged: |
| 107 | |
| 108 | ```typescript |
| 109 | const api = yield* AWS.Lambda.Function("Api", { |
| 110 | main: "./src/handler.ts", |
| 111 | domain: { |
| 112 | name: "api.example.com", |
| 113 | dns: Cloudflare.DNS.Adapter({ zone: "example.com" }), |
| 114 | }, |
| 115 | }); |
| 116 | // api.domainUrl → "https://api.example.com" |
| 117 | ``` |
| 118 | |
| 119 | ### Cloudflare Workers on another DNS host |
| 120 | |
| 121 | A Worker's native custom domain requires the hostname to be in a Cloudflare |
| 122 | zone. When the hostname's DNS lives in Route 53 or Hetzner, the Worker |
| 123 | serves it through |
| 124 | [Cloudflare for SaaS](https://developers.cloudflare.com/cloudflare-for-platforms/cloudflare-for-saas/start/advanced-settings/worker-as-origin/) |
| 125 | on a Cloudflare zone you own, called the SaaS zone: |
| 126 | |
| 127 | ```typescript |
| 128 | // Once per SaaS zone: an originless proxied record as the fallback origin. |
| 129 | const origin = yield* Cloudflare.DNS.Record("SaasOrigin", { |
| 130 | zoneId: saasZone.zoneId, |
| 131 | name: "customers.my-saas.com", |
| 132 | type: "AAAA", |
| 133 | content: "100::", |
| 134 | proxied: true, |
| 135 | }); |
| 136 | const fallback = yield* Cloudflare.CustomHostname.FallbackOrigin( |
| 137 | "SaasFallback", |
| 138 | { zoneId: saasZone.zoneId, origin: origin.name }, |
| 139 | ); |
| 140 | |
| 141 | yield* Cloudflare.Worker("Api", { |
| 142 | main: "./src/api.ts", |
| 143 | domain: { |
| 144 | name: "app.example.com", |
| 145 | zoneId: saasZone.zoneId, |
| 146 | cnameTarget: fallback.origin, |
| 147 | dns: AWS.Route53.Adapter(), |
| 148 | }, |
| 149 | }); |
| 150 | ``` |
| 151 | |
| 152 | Each hostname becomes a `Cloudflare.CustomHostname.CustomHostname` on the |
| 153 | SaaS zone. The adapter publishes its ownership and certificate `TXT` |
| 154 | records and a `CNAME` to `cnameTarget`, and the Worker gets a |
| 155 | `{hostname}/*` route on the SaaS zone. Cloudflare for SaaS must be enabled |
| 156 | on the zone; without it Cloudflare rejects the custom hostname with |
| 157 | `SaasQuotaNotAllocated`. This path doesn't support `redirects`, `previews`, |
| 158 | or apex hostnames, and the Worker's `url` stays its `workers.dev` URL. |
| 159 | |
| 160 | With `dns` omitted, or set to `Cloudflare.DNS.Adapter()`, the Worker attaches |
| 161 | native custom domains exactly as before. |
| 162 | |
| 163 | ### Fly, Railway, Neon, Prisma, and Hetzner websites |
| 164 | |
| 165 | These platforms host no DNS, so without `dns` you publish the records their |
| 166 | custom-domain resources list. Use the object form of `domain` to publish |
| 167 | them through an adapter: |
| 168 | |
| 169 | ```typescript |
| 170 | yield* Fly.Website.Vite("Web", { |
| 171 | domain: { |
| 172 | name: "app.example.com", |
| 173 | dns: AWS.Route53.Adapter(), |
| 174 | }, |
| 175 | }); |
| 176 | ``` |
| 177 | |
| 178 | On `Hetzner.Website.*`, `dns` replaces the `zone` prop, so the site can |
| 179 | also publish its `A` record in Cloudflare or Route 53. |
| 180 | |
| 181 | ## What gets created |
| 182 | |
| 183 | An adapter declares ordinary record resources of its own cloud, so they |
| 184 | appear in the plan and in state like any other resource: |
| 185 | |
| 186 | | Adapter | Hostname aliases | Validation and verification records | |
| 187 | | --- | --- | --- | |
| 188 | | Cloudflare | `Cloudflare.DNS.Records` (`CNAME`), or `Cloudflare.DNS.RecordList` for addresses | `Cloudflare.DNS.RecordList` | |
| 189 | | Route 53 | `AWS.Route53.Record` (`A`/`AAAA` alias or `CNAME`), `AWS.Route53.Records` for a Router | `AWS.Route53.RecordList` | |
| 190 | | Hetzner | `Hetzner.DNS.RecordList` | `Hetzner.DNS.RecordList` | |
| 191 | |
| 192 | Record ownership follows the rest of Alchemy: |
| 193 | |
| 194 | - **Alias records** are owned by the stack. The first deploy refuses to |
| 195 | overwrite a record that already exists at a hostname unless you pass |
| 196 | `--adopt`. Removing the domain deletes the records. |
| 197 | - **Validation and verification records** are added next to any other |
| 198 | values at the same name and removed on destroy. ACM validation `CNAME`s |
| 199 | are the exception: ACM reuses one `CNAME` per name for every certificate, |
| 200 | so they stay in the zone when the certificate is deleted. |
| 201 | |
| 202 | The Route 53 adapter declares the same resources, with the same logical |
| 203 | IDs, that AWS composites declared before `dns` existed, so upgrading a |
| 204 | stack that uses Route 53 plans no changes. |
| 205 | |
| 206 | ## Switching DNS hosts |
| 207 | |
| 208 | Changing `domain.dns` swaps the record resources: the next deploy creates |
| 209 | the records at the new host and deletes them from the old one, each through |
| 210 | its own provider. Update the domain's nameservers at the registrar once the |
| 211 | new records are in place. |
| 212 | |
| 213 | ## How adapters work |
| 214 | |
| 215 | `domain.dns` holds plain data, for example |
| 216 | `{ type: "Cloudflare.DNS", zone: "example.com" }`. That keeps it safe in any |
| 217 | resource's props, in state, and across the `alchemy dev` sidecar. |
| 218 | |
| 219 | While the stack program runs, the platform resolves the adapter registered |
| 220 | for that `type`. Each DNS host's `providers()` layer registers its adapter. |
| 221 | The adapter's methods only declare resources. No provider calls an adapter |
| 222 | while it deploys, so destroying a stack or cleaning up an orphan needs |
| 223 | nothing but state and the record resources' own providers. |
| 224 | |
| 225 | An adapter is three functions that declare record resources. Each receives |
| 226 | the zone and options from the user's `domain.dns` alongside its own |
| 227 | arguments: |
| 228 | |
| 229 | | Function | Declares | |
| 230 | | --- | --- | |
| 231 | | `alias(id, { zone, name, target, ipv6? })` | Records pointing one hostname at a hostname target (`CNAME`, or a Route 53 alias when `target.route53Alias` is set) or an address target (`A`/`AAAA`) | |
| 232 | | `aliasSet(id, { zone, names?, target })` | A record set that other composites add hostnames to by binding `{ names }`, used by `AWS.Website.Router` | |
| 233 | | `records(id, { zone, records, retain? })` | Explicit records whose values usually come from another resource's outputs | |
| 234 | |
| 235 | ## Build your own adapter |
| 236 | |
| 237 | This walkthrough adds an adapter for a hypothetical "Acme DNS" API. Any |
| 238 | platform's `domain.dns` can then publish records there. |
| 239 | |
| 240 | ### Write the record resource |
| 241 | |
| 242 | An adapter declares resources, so your DNS host first needs a resource that |
| 243 | manages DNS records. The simplest one that covers every adapter function is |
| 244 | a **record list**: one resource that owns a list of |
| 245 | `{ name, type, value }` records. A list fits because platforms often don't |
| 246 | know how many records they need until deploy time. ACM, for example, |
| 247 | returns one validation record per hostname on the certificate. |
| 248 | |
| 249 | ```typescript |
| 250 | // src/acme-dns/RecordList.ts |
| 251 | import { Resource } from "alchemy"; |
| 252 | import type { DnsRecord } from "alchemy/DNS"; |
| 253 | |
| 254 | export interface RecordListProps { |
| 255 | /** Zone that owns the records. Inferred from each name when omitted. */ |
| 256 | zone?: string; |
| 257 | /** Records to publish, e.g. `{ name: "www.example.com", type: "CNAME", value: "d123.cloudfront.net" }`. */ |
| 258 | records: DnsRecord[]; |
| 259 | } |
| 260 | |
| 261 | export type RecordList = Resource< |
| 262 | "AcmeDns.RecordList", |
| 263 | RecordListProps, |
| 264 | { records: DnsRecord[] } |
| 265 | >; |
| 266 | |
| 267 | export const RecordList = Resource<RecordList>("AcmeDns.RecordList"); |
| 268 | ``` |
| 269 | |
| 270 | Its provider's `reconcile` creates each listed record and deletes the ones |
| 271 | it created before that are no longer listed; `delete` removes the records it |
| 272 | created. Build it as described in |
| 273 | [Custom Provider](/infrastructure-as-code/custom-provider). |
| 274 | `Cloudflare.DNS.RecordList` and `AWS.Route53.RecordList` are complete |
| 275 | references. |
| 276 | |
| 277 | ### Write the data constructor |
| 278 | |
| 279 | The constructor returns the plain data users put in `domain.dns`. Pick a |
| 280 | `type` that's unique to your adapter: |
| 281 | |
| 282 | ```typescript |
| 283 | // src/acme-dns/Adapter.ts |
| 284 | import type { DnsConfig } from "alchemy/DNS"; |
| 285 | |
| 286 | export const Adapter = ( |
| 287 | options: { zone?: string } = {}, |
| 288 | ): DnsConfig<"AcmeDns"> => ({ |
| 289 | type: "AcmeDns", |
| 290 | ...(options.zone === undefined ? {} : { zone: options.zone }), |
| 291 | }); |
| 292 | ``` |
| 293 | |
| 294 | ### Implement the adapter |
| 295 | |
| 296 | The adapter is an object with three functions, each returning the resource |
| 297 | it declares: |
| 298 | |
| 299 | ```typescript |
| 300 | // src/acme-dns/Adapter.ts |
| 301 | import * as DNS from "alchemy/DNS"; |
| 302 | import * as RemovalPolicy from "alchemy/RemovalPolicy"; |
| 303 | import type { Providers } from "./Providers.ts"; |
| 304 | import { RecordList } from "./RecordList.ts"; |
| 305 | |
| 306 | export const adapter = { |
| 307 | // Point one hostname at the platform: a CNAME, or A/AAAA records. |
| 308 | alias: (id, { zone, name, target }) => |
| 309 | RecordList(id, { zone, records: DNS.aliasRecords(name, target) as DNS.DnsRecord[] }), |
| 310 | // Several hostnames at one hostname target. Give RecordList a `{ names }` |
| 311 | // binding contract to let sites attached to an AWS.Website.Router add theirs. |
| 312 | aliasSet: (id, { zone, names = [], target }) => |
| 313 | RecordList(id, { |
| 314 | zone, |
| 315 | records: names.map((name) => ({ name, type: "CNAME" as const, value: target.hostname as string })), |
| 316 | }), |
| 317 | // Records the platform computed, e.g. certificate validation CNAMEs. |
| 318 | records: (id, { zone, records, retain }) => |
| 319 | RecordList(id, { zone, records: records as DNS.DnsRecord[] }).pipe( |
| 320 | retain ? RemovalPolicy.retain() : (effect) => effect, |
| 321 | ), |
| 322 | } satisfies DNS.DnsAdapter<Providers>; |
| 323 | ``` |
| 324 | |
| 325 | `satisfies DNS.DnsAdapter<Providers>` types the arguments and checks that |
| 326 | each function declares resources of your cloud. Honor `retain`: platforms |
| 327 | set it for records that must outlive the resource, such as ACM validation |
| 328 | `CNAME`s. |
| 329 | |
| 330 | ### Register it in your providers layer |
| 331 | |
| 332 | `adapterLayer` only registers the adapter service. It does not register the |
| 333 | native record providers declared by `alias`, `aliasSet`, or `records`, so |
| 334 | include those providers in the host package's `providers()` layer as well. |
| 335 | |
| 336 | `DNS.adapterLayer` registers the adapter under the `type` your constructor |
| 337 | returns. Merge it into the same `providers()` layer that registers your |
| 338 | record providers: |
| 339 | |
| 340 | ```typescript |
| 341 | // src/acme-dns/Providers.ts |
| 342 | import * as DNS from "alchemy/DNS"; |
| 343 | import * as Layer from "effect/Layer"; |
| 344 | import { adapter } from "./Adapter.ts"; |
| 345 | |
| 346 | export const providers = () => |
| 347 | Layer.mergeAll(RecordListProvider(), DNS.adapterLayer("AcmeDns", adapter)); |
| 348 | ``` |
| 349 | |
| 350 | ### Use it from a stack |
| 351 | |
| 352 | Pass the data constructor as `domain.dns` on any platform, and add your |
| 353 | layer to the stack's providers: |
| 354 | |
| 355 | ```typescript |
| 356 | const stack = Alchemy.Stack( |
| 357 | "Web", |
| 358 | { providers: Layer.mergeAll(AWS.providers(), AcmeDns.providers()) }, |
| 359 | Effect.gen(function* () { |
| 360 | yield* AWS.Website.StaticSite("Site", { |
| 361 | path: "./dist", |
| 362 | domain: { name: "app.example.com", dns: AcmeDns.Adapter() }, |
| 363 | }); |
| 364 | }), |
| 365 | ); |
| 366 | ``` |
| 367 | |
| 368 | ### Test it |
| 369 | |
| 370 | Test against the real DNS host. Deploy a stack that calls each adapter |
| 371 | function, check the records out of band with the host's API, update the |
| 372 | stack and check that the records converge, then destroy it and check that |
| 373 | they're gone. Start and end every test with `stack.destroy()`: |
| 374 | |
| 375 | ```typescript |
| 376 | test.provider("publishes an alias", (stack) => |
| 377 | Effect.gen(function* () { |
| 378 | yield* stack.destroy(); |
| 379 | yield* stack.deploy( |
| 380 | Effect.gen(function* () { |
| 381 | const dns = yield* DNS.resolve(AcmeDns.Adapter({ zone: "example.com" })); |
| 382 | yield* dns.alias("Web", { name: "www.example.com", target: { hostname: "example.net" } }); |
| 383 | }), |
| 384 | ); |
| 385 | // read the CNAME back through the Acme DNS API and assert on it |
| 386 | yield* stack.destroy(); |
| 387 | // assert the CNAME is gone |
| 388 | }), |
| 389 | ); |
| 390 | ``` |
| 391 | |
| 392 | `packages/integration-tests/test/DNS/Adapter.test.ts` does this for the |
| 393 | built-in adapters. |
| 394 | |
| 395 | ## Troubleshooting |
| 396 | |
| 397 | | Error | Cause and fix | |
| 398 | | --- | --- | |
| 399 | | `DnsAdapterNotRegistered` | `domain.dns` names a host whose `providers()` layer isn't in the stack. Add it, for example `Cloudflare.providers()` for `Cloudflare.DNS.Adapter()`. | |
| 400 | | `OwnedBySomeoneElse` | A record already exists at a hostname the domain aliases. Delete it, or deploy with `--adopt` to take it over. | |
| 401 | | `CertificateCaaError` | A `CAA` record on the domain doesn't authorize Amazon, so ACM refused to issue the certificate. Add `0 issue "amazon.com"` (and `issuewild` for wildcard names) at the zone apex and redeploy. Alchemy never writes `CAA` records. | |
| 402 | | `DnsAdapterError` | The DNS host can't publish a record as requested, for example a `CNAME` at the apex of a pinned Hetzner zone. Use an address target or a host that flattens `CNAME`s. | |
| 403 | | `SaasQuotaNotAllocated` | A Worker's `domain.dns` names another host, but Cloudflare for SaaS isn't enabled on the SaaS zone. | |
| 404 | |
| 405 | ## Where to go next |
| 406 | |
| 407 | - [AWS custom domains](/aws/networking/custom-domains): certificates, hosted |
| 408 | zones, and API Gateway domains on AWS. |
| 409 | - [Cloudflare domains](/cloudflare/networking/domains): zones and DNS |
| 410 | records on Cloudflare. |
| 411 | - [Custom Provider](/infrastructure-as-code/custom-provider): implement the |
| 412 | record resources behind a new adapter. |