Skip to main content

​
Prerequisites

Complete these before adding a domain: A domain is declared in fjall/domains/<zone>/infrastructure.ts with the typed Domain construct. The file you edit is the file that deploys. See Domain for the construct API and fjall domain for every verb and flag.

​
Create the domain

Scaffold a new domain in your project root:
This writes fjall/domains/example.com/infrastructure.ts and registers the domain in fjall-config.json, so the organisation cascade can deploy it. Edit the declaration to add your records: MX, TXT, DKIM, whatever the zone needs.

​
Or import an existing zone

Already hosting the domain in Route 53? Import it:
With a domain argument the import does not check who owns each record, so it also declares records another live stack owns. Run fjall domain import with no domain argument, in a terminal, for the guided import, which leaves the records it proves another stack owns unselected. Either way, work through Adopt a live Route 53 zone before the first deploy. Or adopt the live zone by reference while writing the declaration yourself:
If the domain is registered outside AWS with no Route 53 zone yet, plain fjall domain create is the right start. Delegation to Route 53 happens after the first deploy.

​
Deploy the zone

The deploy echoes the resolved AWS account and target before anything else runs, then creates the hosted zone, the declared records, and DNS-validated ACM certificates. Pick the account explicitly with -t, --target <name>. An unresolvable target fails closed with the available targets listed.

​
domain deploy options

Run --plan first in CI, hand the plan to a reviewer, then apply it with --approval-token. See Destructive Changes for the full plan-then-apply workflow.
The first deploy of an adopted zone runs the record-takeover ceremony. The deploy stops with a ticket naming each record both the live zone and your declaration claim, and you consent per record with --remediate '<name>/<TYPE>'=recreate. There is no blanket flag. Consent withheld means exit code 4: nothing released, nothing deployed. Consent given deletes each named record from the live zone before the domain stack creates it again, and a failed deploy recreates none of them. See Destructive Changes.

​
Verify delegation

Check that the domain’s nameservers point at Route 53:
For a domain registered outside AWS, print the nameservers to set at your registrar:
Update the NS records at your registrar, wait for propagation (typically a few hours), and re-run fjall domain verify until it reports the delegation live.

​
Point your application at it

Set the application’s domain. That is the whole mechanism. At deploy time the CLI injects a managed domain binding with literal values (hosted zone ID, certificate ARNs), so the application binds to the zone with no extra wiring, across accounts and regions. For a static site, pass the domain at create time:
Or set domain: "example.com" in the pattern’s infrastructure.ts. A compute application declares it the same way, as domain: "api.example.com" on the ComputeFactory (see Application Binding). Then deploy the application as normal:
The pattern creates the alias record in the zone and attaches the domain’s certificate. The deploy output includes your custom-domain URL.

​
Keep the zone clean

List every live record with its ownership classification (declared, satellite, residue, or unknown):
Report the classification of the whole zone, then delete provably orphaned residue by named consent:
--fix runs the same ceremony as deploy. A ticket names each residue record, you consent per row, and withheld consent exits 4 with nothing deleted. Records classified unknown are never offered for deletion.

​
Next Steps

fjall domain

Every domain verb, flag, and exit code.

Domain construct

Declare zones, records, certificates, and delegation in infrastructure.ts.

Static Site Pattern

Serve a static site on your domain via CloudFront.

Destructive Changes

How the destruction ceremony and named consents work.