Fjall Docs — deploy AWS infrastructure into your own account

Overview

The static-site pattern deploys a folder of built files (a Next.js export, a Vite build, an Astro site, hand-written HTML) to AWS with production hardening you would otherwise assemble by hand:

Private S3 bucket. No public bucket policy. CloudFront reaches it via Origin Access Control (OAC).
CloudFront CDN. HTTPS, HTTP/2 and HTTP/3, global edge caching.
Clean URLs. /about serves about.html or about/index.html to match your build output, or falls back to index.html for SPAs.
Security headers. HSTS, nosniff, frame denial, referrer policy.
Custom domain. ACM certificate and Route53 alias record, created automatically.
Contact form. An optional /api/contact endpoint (Lambda Function URL to SES) so a static site can still receive enquiries.

There is no VPC, no database, no container and no compute stack. The whole application lands in a single CDN stack, and a low-traffic site costs approximately nothing to run.

The pattern serves the files your build produces. It does not run a server. If your site needs SSR or API routes beyond the contact form, use the Payload pattern instead.

Quick Start

1. Have a build that emits static files

Any tool works, as long as one command produces a folder of files:

Tool	Build command	Output folder
Next.js (`output: "export"`)	`npm run build`	`out`
Vite / Astro	`npm run build`	`dist`
Eleventy	`npm run build`	`_site`
Plain HTML	`true` (no-op)	`.`

2. Create the Fjall application

cd my-site
fjall create app \
  --name my-site \
  --pattern staticsite \
  --source ../.. \
  --build-command "npm run build" \
  --output-dir out

All three static-site inputs are required: --source, --build-command and --output-dir. Prefer prompts? Run fjall create, choose Patterns, then Static site. The flow asks for name, build directory, build command, output directory, routing mode, custom domain and contact form. fjall create app on its own opens the six-tier application picker, which lists no patterns.

Paths are written into fjall/my-site/infrastructure.ts and resolved from that directory at deploy time. --source ../.. points at the repo root, and --output-dir is relative to --source.

3. Deploy

fjall deploy my-site

Fjall runs your build command in source, synthesises the CDN stack, and uploads the contents of the output folder to S3. The deploy output includes the CloudFront URL.

What’s Included

Resource	Purpose
S3 Bucket (private)	Site assets, readable only by CloudFront via OAC
CloudFront Distribution	HTTPS, edge caching, clean-URL routing
CloudFront Function	URI rewriting for `multipage` and `directory` routing (`spa` uses error responses instead)
Response Headers Policy	Security headers (when `security.headers` is set)
ACM Certificate	TLS for the custom domain (BYO zones only. A Fjall-managed domain supplies its own `us-east-1` certificate through the binding)
Route53 A Record	Alias to CloudFront (when `domain` is set)
Lambda + Function URL	Contact-form endpoint (when `forms` is set)

No Docker image is built and no ECR repository is created. The deploy artefact is the static files themselves.

Routing Modes

Mode	Behaviour
`multipage` (default)	`/about` and `/about/` both serve `about.html`, one `.html` file per page
`directory`	`/about` and `/about/` both serve `about/index.html`, a directory with an index per page
`spa`	Every non-file path falls back to `index.html` for client-side routing

Pick the mode that matches your build output. Astro’s default layout is directory. Astro with build.format: "file" and Next.js output: "export" produce multipage. fjall apps detect reads Astro’s build.format and prefills the matching mode. Set the mode with --routing <mode> at create time, or routing: "<mode>" in infrastructure.ts. Requests under /api/ and paths containing /. (such as /.well-known/...) are never rewritten in any mode.

Deployment Process

First deploy

fjall deploy my-site

Detects type: "staticsite" in infrastructure.ts
Runs your build command in source (10-minute budget)
Synthesises and deploys the single CDN stack
Uploads the build output to S3 (stale files from previous builds are pruned)
Prints the CloudFront and custom-domain URLs

Subsequent deploys

The same command rebuilds and re-uploads. Only changed files transfer, and pruning keeps the bucket in lockstep with the latest build, so a deleted page disappears from S3 rather than lingering. After the upload, the deployment invalidates the CloudFront distribution (/*), so new content serves immediately instead of after the edge cache TTL (up to 24 hours) expires. AWS grants 1,000 free invalidation paths per month, and /* counts as one path per deploy. For pure TTL semantics, set cdn: { invalidateOnDeploy: false }.

Custom Domain

fjall create app --name my-site --pattern staticsite \
  --source ../.. --build-command "npm run build" --output-dir out \
  --pattern-domain example.com

When domain is set, the pattern needs to know which hosted zone the domain lives in. Zone identity is always explicit, never guessed from the domain’s labels (label-guessing mis-resolved .com.au-style domains and delegated sub-zones):

Fjall-managed domain. Nothing extra to configure. The CLI injects a managed-domain binding at deploy time with literal values: the hosted zone ID and the domain stack’s us-east-1 certificate ARN. CloudFront uses that certificate directly, so redeploying the site never churns a per-site certificate, and the binding works across accounts and regions.
Bring-your-own zone. Set zoneName to the Route53 hosted zone that contains domain, plus hostedZoneId to skip the runtime lookup. The pattern creates a DNS-validated ACM certificate in us-east-1 and attaches it to CloudFront.

Never write a managedDomain key into infrastructure.ts. The binding is deploy-injected through CDK context, and the pattern’s config schema is strict, so a hand-authored managedDomain fails validation with Unrecognized key. Use zoneName for bring-your-own zones, and nothing at all for Fjall-managed domains.

Either way, the pattern creates the alias A record. Its label is derived from domain relative to the zone (example.com in zone example.com is the apex, www.example.com is www). Requires: a Route53 hosted zone containing the domain. See Domain for creating, importing, or adopting zones with fjall domain.

Contact Forms

A static site usually still needs one dynamic thing: a way for visitors to get in touch. Setting forms provisions a Lambda behind https://<domain>/api/contact that emails submissions via SES.

fjall create app --name my-site --pattern staticsite \
  --source ../.. --build-command "npm run build" --output-dir out \
  --pattern-domain example.com \
  --forms-to hello@my-inbox.com

The sender and recipient are separate axes:

Field	Constraint	Default
`from`	Must be an address at `domain` (the verified SES identity)	`noreply@<domain>`
`to`	Any address. Your personal inbox is the common case	(required)

The submitter’s own address goes in Reply-To, so replying from your inbox reaches them directly.

Forms require domain. SES only sends from a verified identity, and the site’s domain is that identity. Before the first submission works, verify the domain in SES (SES console, Verified identities, Create identity, Domain) in the deployment account and region. With the hosted zone in Route53, SES adds the DKIM records automatically. While your account is in the SES sandbox, the to address must also be verified, or request production access.

Wiring a form

POST JSON or form-encoded data with name, email, and message fields. Include an empty _gotcha field as a honeypot. Bots that fill it get a silent success and no email is sent.

<form id="contact">
  <input name="name" placeholder="Name" />
  <input name="email" type="email" placeholder="Email" />
  <textarea name="message" required placeholder="Message"></textarea>
  <input name="_gotcha" style="display:none" tabindex="-1" autocomplete="off" />
  <button type="submit">Send</button>
</form>

<script>
  document.getElementById("contact").addEventListener("submit", async (e) => {
    e.preventDefault();
    const res = await fetch("/api/contact", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(Object.fromEntries(new FormData(e.target))),
    });
    alert(res.ok ? "Thanks, message sent." : "Something went wrong.");
  });
</script>

Abuse posture

The endpoint is public and unauthenticated, so the pattern bounds what a caller can do rather than pretending to authenticate them:

Fixed sender and recipient. Whatever a caller sends, the email can only ever go from noreply@<domain> to your configured address.
Origin gate and CORS. Browsers on other sites cannot POST to it. The allow-origin defaults to https://<domain> (override with --cors-origin).
Honeypot. A filled _gotcha short-circuits to a silent success.
Reserved concurrency. The Lambda is capped (default 5 concurrent executions), so a flood cannot run up the SES bill or drain account-wide Lambda concurrency.
Scoped IAM. The Lambda may call ses:SendEmail only for the site’s domain identity, conditioned on the exact From address.

Security Headers

security: {
  headers: true;
}

Ships four safe defaults: Strict-Transport-Security (max-age 730 days), X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Referrer-Policy: strict-origin-when-cross-origin. HSTS ships scoped to the site’s own host. includeSubdomains and preload stay off unless you ask for them, because both reach beyond this distribution: includeSubdomains binds every subdomain of the apex (a sibling host on plain HTTP becomes unreachable), and preload removal ships on a browser release train measured in months. Opt in with an hsts object, or drop the header with hsts: false:

security: {
  headers: true,
  hsts: { maxAgeDays: 730, includeSubdomains: true, preload: true },
}

Sub-fields you omit from an hsts object take the aggressive defaults (maxAgeDays: 730, includeSubdomains: true, preload: true), so hsts: {} opts into both directives. Content-Security-Policy is deliberately opt-in. A wrong policy silently breaks inline scripts and hydration, so it is never a shipped default:

security: {
  headers: true,
  contentSecurityPolicy: "default-src 'self'; img-src 'self' data:",
}

Pattern Parameters

Full Configuration Example

app.addPattern(
  PatternFactory.build("MySiteStaticSite", {
    type: "staticsite",
    name: "my-site",
    source: "../..",
    build: { command: "npm run build", outputDir: "out" },
    routing: "multipage",
    security: { headers: true },
    domain: "example.com",
    zoneName: "example.com",
    forms: {
      to: "hello@my-inbox.com",
      corsOrigin: "https://example.com",
    },
    cdn: {
      priceClass: "PriceClass_All",
      invalidateOnDeploy: true,
    },
    accessGate: {
      type: "basic-auth",
      username: "preview",
      password: "change-me",
    },
  }),
);

Root Options

Option	Type	Default	Description
`type`	`"staticsite"`	required	Pattern discriminator
`name`	`string`	required	Pattern name (used for resource naming)
`source`	`string`	required	Directory the build runs in and assets upload from
`build`	`object`	required	Build command plus output directory (see below)
`routing`	`"multipage" \| "directory" \| "spa"`	`"multipage"`	Which build-output layout the CDN serves (see Routing Modes)
`security`	`object`	none	Security-header configuration (see below)
`domain`	`string`	none	Custom domain. Required when `forms` is set
`zoneName`	`string`	none	Route53 hosted zone containing `domain` (BYO zones). The pattern validates `domain` against it, and zone identity is never derived from the domain’s labels
`hostedZoneId`	`string`	none	Literal hosted zone ID for `zoneName`. When set, the zone is referenced directly instead of looked up at synth time
`forms`	`object`	none	Contact-form configuration (see below)
`cdn`	`object`	none	CDN tuning: price class, deploy-time invalidation, per-path behaviour overrides (see below)
`accessGate`	`object`	none	Basic-auth staging gate at the edge (see Access Gate below)

The schema is strict, so an unrecognised key fails validation. Zone and certificate identity for a Fjall-managed domain arrives as a deploy-time CDK context injection, not as a config key you author.

Build Options

Option	Type	Description
`command`	`string`	Build command run in `source` (e.g. `"npm run build"`)
`outputDir`	`string`	Folder (relative to `source`) holding the built site

Security Options

Option	Type	Default	Description
`headers`	`boolean`	none	Ship the four safe headers
`hsts`	`false \| { maxAgeDays?, includeSubdomains?, preload? }`	730 days, host-scoped	HSTS tuning. `false` drops the header. An object’s omitted sub-fields default to 730 days, `includeSubdomains: true`, `preload: true`
`contentSecurityPolicy`	`string`	none	Opt-in CSP header value

Forms Options

Option	Type	Default	Description
`to`	`string`	required	Where submissions are delivered (any address)
`from`	`string`	`noreply@<domain>`	Envelope sender. Must be an address at `domain`
`corsOrigin`	`string`	`https://<domain>`	Exact origin allowed to POST the form (scheme and host, no path, no trailing slash)
`maxConcurrency`	`number`	`5`	Reserved concurrent executions for the forms Lambda (1 to 100)

CDN Options

Option	Type	Default	Description
`priceClass`	`"PriceClass_100" \| "PriceClass_200" \| "PriceClass_All"`	`"PriceClass_100"`	Which edge locations serve the site (see below)
`invalidateOnDeploy`	`boolean`	`true`	Invalidate the distribution (`/*`) after each deploy’s upload
`behaviours`	`array`	none	Additional per-path CloudFront behaviours (CDN Factory shapes)

priceClass is a latency knob, not a cost knob at small-site traffic. PriceClass_100 serves from North America and Europe only, so an audience in Australia, Asia, or South America crosses an ocean on every request. PriceClass_200 adds Asia but still no Australia or New Zealand. Set "PriceClass_All" for a global or Oceania audience. The price difference at low traffic is effectively zero.

Access Gate Options

Option	Type	Description
`type`	`"basic-auth"`	Gate mechanism (currently one value)
`username`	`string`	Basic-auth username
`password`	`string`	Basic-auth password

The gate is a CloudFront viewer function that challenges every request with HTTP Basic auth before the routing rewrite runs. Use it to keep a not-yet-launched site out of casual view and search indexes while a client signs off, then remove it at launch.

The access gate is an obscurity gate, not a security boundary. The credentials sit in plain text in infrastructure.ts and in the distribution’s function code, and the origin objects are unchanged. Do not protect sensitive content with it.

Troubleshooting

Form POST returns 403

The Origin/Referer gate rejected the request. The browser must send the form from the configured origin. Check that corsOrigin matches the site origin exactly (https://example.com, no path, no trailing slash), and that you are not testing from localhost against the deployed endpoint.

Form POST returns 502

SES refused the send. Almost always identity verification: the domain is not verified as an SES identity in the deployment account and region, or the account is in the SES sandbox and the to address is unverified. Check the identity’s status in the SES console.

Clean URLs return 403 or 404

Confirm routing matches the build output. Use multipage for one .html file per page, directory for a directory with an index.html per page, and spa for a client-side router that needs every path to serve index.html.

Deploy fails: build output not found

outputDir is resolved relative to source. Run the build command manually in source and check which folder it emits. Next.js exports to out, Vite and Astro to dist.

Costs

Estimated monthly costs for a low-traffic site:

Resource	Cost
S3	~ $0.03 to$ 0.50 (storage plus requests)
CloudFront	~$0 (1 TB/month free tier)
Lambda (forms)	~$0 (pay per request)
SES	$0.10 per 1,000 emails
CloudFront invalidation	~$0 (1,000 free paths/month, `/*` = 1 path per deploy)
Route53 hosted zone	$0.50 (custom domain only)
Total	~ $0 to$ 1/month

Breaking Out the Pattern

The pattern is the opinionated layer. Everything beneath it stays yours. Three escape tiers, in order of reach:

1. Typed knobs

Most customisation needs a config field, not surgery. routing, security (headers, HSTS and CSP), forms, cdn.priceClass, cdn.invalidateOnDeploy, cdn.behaviours (per-path CloudFront overrides), and accessGate are all part of the pattern’s own surface, documented above.

2. Instance access, raw CDK underneath

app.addPattern returns the constructed pattern, and its getters reach every resource it created:

const site = app.addPattern(
  PatternFactory.build("MySiteStaticSite", {
    type: "staticsite",
    name: "my-site",
    source: "../..",
    build: { command: "npm run build", outputDir: "out" },
  }),
);

// The concrete S3 Bucket. Add lifecycle rules, CORS, notifications:
site
  .getBucket()
  .getBucket()
  .addLifecycleRule({
    expiration: Duration.days(90),
  });

// The CloudFront Distribution. Extra behaviours, raw CDK access:
site.getCdn().getDistribution().addBehavior("/custom/*", customOrigin);

// The contact-form Lambda (when `forms` is set). It IS the CDK Function:
site.getFormsFunction()?.addEnvironment("EXTRA_VAR", "value");

// The security-headers policy (when `security.headers` is set):
site.getResponseHeadersPolicy();

Everything these getters return is a real CDK construct, so anything CDK can express is reachable from here without leaving the pattern.

3. Full decomposition with StorageFactory and CdnFactory

For total control, compose the resources yourself instead of using the pattern. The CDN Factory page’s Static Website with S3 example is the starting point: a private bucket via StorageFactory, fronted by CdnFactory with OAC.

A hand-composed site brings its own build. Fjall runs the build command for type: "staticsite" patterns only. A factory-composed application has no build step, and fjall deploy warns that it deploys the files already on disk. Build before you deploy (locally or in CI), or the bucket receives whatever bytes the previous build left behind.

Next Steps

Payload Pattern

Need a CMS or SSR? Deploy Payload on Lambda

CDN Factory

Advanced CloudFront behaviours and origins

Storage Factory

S3 bucket configuration in depth

Deploy Application

General deployment guide

Fjall:

Deploy Application - General deployment guide
CDN Factory - CloudFront configuration
Storage Factory - S3 options
Domain - Hosted zones and custom domains

External:

Next.js Static Exports - output: "export" setup
Amazon SES identity verification - Verifying the sending domain

​Overview

​Quick Start

​1. Have a build that emits static files

​2. Create the Fjall application

​3. Deploy

​What’s Included

​Routing Modes

​Deployment Process

​First deploy

​Subsequent deploys

​Custom Domain

​Contact Forms

​Wiring a form

​Abuse posture

​Security Headers

​Pattern Parameters

​Full Configuration Example

​Root Options

​Build Options

​Security Options

​Forms Options

​CDN Options

​Access Gate Options

​Troubleshooting

​Form POST returns 403

​Form POST returns 502

​Clean URLs return 403 or 404

​Deploy fails: build output not found

​Costs

​Breaking Out the Pattern

​1. Typed knobs

​2. Instance access, raw CDK underneath

​3. Full decomposition with StorageFactory and CdnFactory

​Next Steps

Payload Pattern

CDN Factory

Storage Factory

Deploy Application

​Related Documentation

Overview

Quick Start

1. Have a build that emits static files

2. Create the Fjall application

3. Deploy

What’s Included

Routing Modes

Deployment Process

First deploy

Subsequent deploys

Custom Domain

Contact Forms

Wiring a form

Abuse posture

Security Headers

Pattern Parameters

Full Configuration Example

Root Options

Build Options

Security Options

Forms Options

CDN Options

Access Gate Options

Troubleshooting

Form POST returns 403

Form POST returns 502

Clean URLs return 403 or 404

Deploy fails: build output not found

Costs

Breaking Out the Pattern

1. Typed knobs

2. Instance access, raw CDK underneath

3. Full decomposition with StorageFactory and CdnFactory

Next Steps

Related Documentation