The best way to control Claude Code, Codex and more from any computer or phone

main
mdx 275 lines 9.63 KB
Raw
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