The best way to control Claude Code, Codex and more from any computer or phone
| 1 | --- |
| 2 | title: Custom domains with Route53 + ACM |
| 3 | description: Serve your site or API from your own domain — DNS-validated ACM certificates, Route 53 or another DNS host through a DNS adapter, and the domain prop on Website resources and Lambda Functions. |
| 4 | sidebar: |
| 5 | order: 6 |
| 6 | --- |
| 7 | |
| 8 | A custom domain on AWS is three moving parts: a TLS certificate (ACM), DNS |
| 9 | records (Route 53, or another DNS host such as Cloudflare), and wiring both |
| 10 | into whatever serves traffic (CloudFront, a load balancer, or API Gateway). |
| 11 | For websites, load-balanced ECS services, and Lambda Functions, Alchemy |
| 12 | collapses all three into a single `domain` prop; for APIs and anything |
| 13 | bespoke, the same primitives — `AWS.ACM.Certificate` and |
| 14 | `AWS.Route53.Record` — are available directly. |
| 15 | |
| 16 | ## The one-prop path: `domain` on Website resources |
| 17 | |
| 18 | `AWS.Website.Router`, `AWS.Website.SsrSite`, and a standalone |
| 19 | `AWS.Website.StaticSite` all accept the same `domain` shape: |
| 20 | |
| 21 | ```typescript |
| 22 | const router = yield* AWS.Website.Router("WebsiteRouter", { |
| 23 | domain: { |
| 24 | name: "app.example.com", |
| 25 | hostedZoneId: "Z1234567890", |
| 26 | aliases: ["www.app.example.com"], |
| 27 | }, |
| 28 | routes: { |
| 29 | "/*": site.routeTarget, |
| 30 | }, |
| 31 | }); |
| 32 | ``` |
| 33 | |
| 34 | With `hostedZoneId` set, Alchemy requests a DNS-validated ACM certificate |
| 35 | covering `name` plus every alias, upserts the validation records into your |
| 36 | zone, waits for issuance, attaches the certificate to the CloudFront |
| 37 | distribution, and creates an `A` alias record for each hostname. The |
| 38 | resource's `url` output becomes `https://app.example.com`. When a site is |
| 39 | attached to a `Router`, put `domain` on the Router — passing it to the |
| 40 | attached `StaticSite` as well is an error. |
| 41 | |
| 42 | ## Bring your own certificate |
| 43 | |
| 44 | If you already have an ACM certificate, pass its ARN as `cert` and Alchemy |
| 45 | skips certificate creation: |
| 46 | |
| 47 | ```typescript |
| 48 | domain: { |
| 49 | name: "app.example.com", |
| 50 | hostedZoneId: "Z1234567890", |
| 51 | cert: existingCertificateArn, |
| 52 | }, |
| 53 | ``` |
| 54 | |
| 55 | DNS records are still managed for you — only the certificate step is |
| 56 | replaced. The certificate must cover the domain name and every alias you |
| 57 | list. |
| 58 | |
| 59 | ## Use a domain on another DNS host |
| 60 | |
| 61 | If the domain's DNS lives outside Route 53 — for example, a domain |
| 62 | registered with Cloudflare Registrar — pass the DNS host's |
| 63 | [adapter](/infrastructure-as-code/dns-adapters) as `dns`: |
| 64 | |
| 65 | ```typescript |
| 66 | const site = yield* AWS.Website.StaticSite("Site", { |
| 67 | path: "./dist", |
| 68 | domain: { |
| 69 | name: "app.example.com", |
| 70 | aliases: ["www.app.example.com"], |
| 71 | dns: Cloudflare.DNS.Adapter(), |
| 72 | }, |
| 73 | }); |
| 74 | ``` |
| 75 | |
| 76 | The certificate is still issued by ACM, but its validation `CNAME`s are |
| 77 | written to the Cloudflare zone (always DNS-only), and each hostname gets a |
| 78 | `CNAME` to the CloudFront distribution — Cloudflare flattens it at the zone |
| 79 | apex. The zone is inferred from each hostname; pin it with |
| 80 | `Cloudflare.DNS.Adapter({ zone: "example.com" })`. The same `dns` option works |
| 81 | on `AWS.Website.Router` (including hostnames bound by attached sites), |
| 82 | `AWS.Website.SsrSite`, the `domain` of an `AWS.ECS.Service` load balancer, and |
| 83 | a Lambda Function's `domain`. Include `Cloudflare.providers()` alongside |
| 84 | `AWS.providers()` in the stack. `Hetzner.DNS.Adapter()` works the same way |
| 85 | for a domain on Hetzner DNS. |
| 86 | |
| 87 | Records are DNS-only by default. `Cloudflare.DNS.Adapter({ proxied: true })` |
| 88 | puts Cloudflare's CDN in front of CloudFront — set the zone's SSL/TLS mode to |
| 89 | Full (strict) if you do. Validation records are left in the zone when a |
| 90 | certificate is deleted: ACM reuses the same `CNAME` for every certificate on |
| 91 | a name. |
| 92 | |
| 93 | ## Manage DNS elsewhere |
| 94 | |
| 95 | Set `dns: false` to skip DNS entirely: |
| 96 | |
| 97 | ```typescript |
| 98 | domain: { |
| 99 | name: "app.example.com", |
| 100 | cert: existingCertificateArn, |
| 101 | dns: false, |
| 102 | }, |
| 103 | ``` |
| 104 | |
| 105 | No records are created, so you point your DNS provider at the distribution's |
| 106 | domain name yourself. `dns: false` requires `cert` — without DNS access |
| 107 | Alchemy can't complete DNS validation for a new certificate, so you must |
| 108 | bring one. |
| 109 | |
| 110 | ## Create or reference a hosted zone |
| 111 | |
| 112 | The `domain` prop and the primitives below both key off a hosted zone ID. If |
| 113 | the zone lives outside your stack, pass its ID as a plain string; to manage |
| 114 | it in the stack, use `AWS.Route53.HostedZone`: |
| 115 | |
| 116 | ```typescript |
| 117 | const zone = yield* AWS.Route53.HostedZone("Zone", { |
| 118 | name: "example.com", |
| 119 | }); |
| 120 | ``` |
| 121 | |
| 122 | `zone.id` is the hosted zone ID (without the `/hostedzone/` prefix) and |
| 123 | `zone.nameServers` lists the authoritative name servers — set these as `NS` |
| 124 | records at your registrar (or parent zone) to delegate the domain. Set |
| 125 | `forceDestroy: true` if you want `destroy` to delete any remaining records |
| 126 | before deleting the zone. |
| 127 | |
| 128 | ## Request a DNS-validated certificate |
| 129 | |
| 130 | `AWS.ACM.Certificate` requests a certificate and, when you give it a |
| 131 | `hostedZoneId`, handles validation end to end: |
| 132 | |
| 133 | ```typescript |
| 134 | const cert = yield* AWS.ACM.Certificate("WebsiteCertificate", { |
| 135 | domainName: "app.example.com", |
| 136 | subjectAlternativeNames: ["www.app.example.com"], |
| 137 | hostedZoneId: zone.id, |
| 138 | }); |
| 139 | ``` |
| 140 | |
| 141 | The provider upserts the DNS validation records ACM asks for into the zone, |
| 142 | waits for Route 53 to propagate them, and blocks until the certificate |
| 143 | reaches `ISSUED` — so `cert.certificateArn` is ready to attach the moment |
| 144 | the effect resolves. |
| 145 | |
| 146 | When the validation records live on another DNS host, request the |
| 147 | certificate with `dnsValidation: "external"`, publish its records, and wait |
| 148 | with `AWS.ACM.CertificateValidation`: |
| 149 | |
| 150 | ```typescript |
| 151 | const cert = yield* AWS.ACM.Certificate("WebsiteCertificate", { |
| 152 | domainName: "app.example.com", |
| 153 | dnsValidation: "external", |
| 154 | }); |
| 155 | yield* Cloudflare.DNS.RecordList("WebsiteCertificateValidation", { |
| 156 | records: cert.domainValidationOptions.pipe( |
| 157 | Output.map(AWS.ACM.validationRecordsOf), |
| 158 | ), |
| 159 | }); |
| 160 | const issued = yield* AWS.ACM.CertificateValidation("WebsiteCertificateIssued", { |
| 161 | certificateArn: cert.certificateArn, |
| 162 | }); |
| 163 | ``` |
| 164 | |
| 165 | `issued.certificateArn` resolves once ACM issues the certificate, so |
| 166 | resources that take it deploy after issuance. The `domain` props above do |
| 167 | this for you when `dns` names another host. Certificates are requested in `us-east-1`, the region |
| 168 | CloudFront requires for viewer certificates. ACM certificates are immutable: |
| 169 | changing the domain name, SANs, or validation settings replaces the |
| 170 | certificate with a new one. |
| 171 | |
| 172 | ## Alias a record to CloudFront |
| 173 | |
| 174 | `AWS.Route53.Record` manages a single record set; an `A` record with |
| 175 | `aliasTarget` points a hostname at a CloudFront distribution: |
| 176 | |
| 177 | ```typescript |
| 178 | yield* AWS.Route53.Record("WebsiteAlias", { |
| 179 | hostedZoneId: zone.id, |
| 180 | name: "app.example.com", |
| 181 | type: "A", |
| 182 | aliasTarget: { |
| 183 | hostedZoneId: distribution.hostedZoneId, |
| 184 | dnsName: distribution.domainName, |
| 185 | }, |
| 186 | }); |
| 187 | ``` |
| 188 | |
| 189 | Note that `aliasTarget.hostedZoneId` is the *distribution's* hosted zone ID |
| 190 | (an attribute CloudFront exposes), not your own zone's. Records are written |
| 191 | with `UPSERT` — create and update are the same operation — and the provider |
| 192 | waits for the Route 53 change to reach `INSYNC` before returning, so the |
| 193 | record is live when the deploy finishes. |
| 194 | |
| 195 | ## Custom domain for a Lambda Function |
| 196 | |
| 197 | Function URLs can't serve a custom hostname. Set `domain` on |
| 198 | `AWS.Lambda.Function` and Alchemy puts an API Gateway v2 HTTP API in front |
| 199 | of the Function, with a regional certificate, an API Gateway domain name per |
| 200 | hostname, and the DNS records: |
| 201 | |
| 202 | ```typescript |
| 203 | const api = yield* AWS.Lambda.Function("Api", { |
| 204 | main: "./src/handler.ts", |
| 205 | domain: "api.example.com", |
| 206 | }); |
| 207 | // api.domainUrl → "https://api.example.com" |
| 208 | ``` |
| 209 | |
| 210 | The HTTP API uses payload format 2.0, the same event shape as a Function |
| 211 | URL, so a `fetch` handler works unchanged. The object form takes `aliases`, |
| 212 | `hostedZoneId`, and `dns` like the Website `domain` prop. |
| 213 | |
| 214 | ## Custom domain for API Gateway |
| 215 | |
| 216 | For a REST API, create an `AWS.ApiGateway.DomainName` with a certificate and |
| 217 | map your API's stage onto it with a `BasePathMapping`: |
| 218 | |
| 219 | ```typescript |
| 220 | const domain = yield* AWS.ApiGateway.DomainName("ApiDomain", { |
| 221 | domainName: "api.example.com", |
| 222 | regionalCertificateArn: cert.certificateArn, |
| 223 | endpointConfiguration: { types: ["REGIONAL"] }, |
| 224 | securityPolicy: "TLS_1_2", |
| 225 | }); |
| 226 | |
| 227 | yield* AWS.ApiGateway.BasePathMapping("Root", { |
| 228 | domainName: domain.domainName, |
| 229 | restApiId: api.restApiId, |
| 230 | stage: "prod", |
| 231 | }); |
| 232 | ``` |
| 233 | |
| 234 | One region caveat: a `REGIONAL` domain needs its certificate in the API's own |
| 235 | region, while `AWS.ACM.Certificate` always issues in `us-east-1`. Deploying |
| 236 | to `us-east-1` works as written; in any other region, pass the ARN of a |
| 237 | certificate that already exists there as `regionalCertificateArn`. |
| 238 | |
| 239 | ## Point DNS at the API |
| 240 | |
| 241 | The `DomainName` resource exposes the regional endpoint to alias to: |
| 242 | |
| 243 | ```typescript |
| 244 | yield* AWS.Route53.Record("ApiAlias", { |
| 245 | hostedZoneId: zone.id, |
| 246 | name: "api.example.com", |
| 247 | type: "A", |
| 248 | aliasTarget: { |
| 249 | hostedZoneId: domain.regionalHostedZoneId.as<string>(), |
| 250 | dnsName: domain.regionalDomainName.as<string>(), |
| 251 | }, |
| 252 | }); |
| 253 | ``` |
| 254 | |
| 255 | `regionalDomainName` / `regionalHostedZoneId` are the alias target for |
| 256 | regional endpoints (edge-optimized domains expose |
| 257 | `distributionDomainName` / `distributionHostedZoneId` instead). The `.as<string>()` |
| 258 | narrows the attribute's type — API Gateway only populates the regional fields |
| 259 | for regional endpoint configurations. |
| 260 | |
| 261 | ## Where next |
| 262 | |
| 263 | - [Websites on AWS](/aws/frontend/websites) — the `domain` prop in the context of the |
| 264 | full websites surface |
| 265 | - [Deploy a static site](/aws/frontend/static-site) — Router composition and |
| 266 | cache invalidation |
| 267 | - [REST API (API Gateway v1)](/aws/apis/api-gateway) — the API this |
| 268 | domain fronts |
| 269 | - Reference: [Certificate](/providers/aws/acm/certificate), |
| 270 | [Record](/providers/aws/route53/record), |
| 271 | [HostedZone](/providers/aws/route53/hostedzone), |
| 272 | [DomainName](/providers/aws/apigateway/domainname), |
| 273 | [Cloudflare DNS Records](/providers/cloudflare/dns/records) |
| 274 | - [DNS Adapters](/infrastructure-as-code/dns-adapters) — publish records on |
| 275 | another DNS host, or build an adapter for your own |