Hosting

The Hosting construct provides frontend deployment with server-side rendering (SSR) support. Hosting auto-detects your frontend framework (Next.js, Nuxt, Astro, or SPA) and provisions the required AWS resources. Import from @aws-blocks/blocks/cdk and use in your CDK layer file (aws-blocks/index.cdk.ts).

Locally, the development server serves your frontend at http://localhost:3000 with hot reload. On AWS, Hosting provisions an Amazon CloudFront distribution with an Amazon S3 origin, AWS Lambda compute for SSR, an optional AWS WAF, monitoring dashboards, and DNS records. Hosting also supports custom domains and skew protection for zero-downtime deployments.

Use Hosting in the CDK layer, not in the IFC layer. The npm run deploy command includes Hosting automatically. For sandbox deployments (npm run sandbox), the deploy skips hosting because sandboxes focus on backend hot-swapping.

What Hosting provisions

On AWS, a single Hosting construct provisions a complete, production-ready frontend stack:

• Amazon CloudFront – a global content delivery network (CDN) distribution that serves your site from edge locations close to your users

• Amazon S3 – an origin bucket that stores your static assets (HTML, CSS, JavaScript, images)

• AWS Lambda – server-side rendering (SSR) compute for framework routes that render on the server. Applies to SSR frameworks only. Hosting skips this resource for single-page applications (SPAs) and static sites.

• Custom domains with TLS – optional Amazon Route 53 records and an AWS Certificate Manager (ACM) certificate for your own domain over HTTPS

• AWS WAF – optional web application firewall rules, including rate limiting

• Amazon CloudWatch monitoring – alarms for Amazon CloudFront 5xx rates, AWS Lambda errors and throttles, and revalidation failures (enabled by default)

• Skew protection – cookie-based pinning that keeps a user’s session on a single build during rolling deployments (enabled by default)

When you provide the api prop, Hosting also adds Amazon CloudFront behaviors that proxy backend API requests through the same domain as your frontend. Your frontend calls the API with relative URLs (for example, /aws-blocks/…​). Because the frontend and API share a single origin, you avoid cross-origin resource sharing (CORS) concerns.

Supported frameworks

Hosting detects your framework from your package.json dependencies and selects the matching adapter. SSR frameworks deploy with AWS Lambda compute. SPA frameworks deploy as static assets that Amazon CloudFront serves from an Amazon S3 origin.

Framework	Rendering	Detected from
Next.js	SSR	next in dependencies
Nuxt	SSR	nuxt or nitropack in dependencies
Astro	Static or SSR	astro in dependencies
Nitro-based (SolidStart, TanStack Start)	SSR	@solidjs/start, @tanstack/start, or nitropack in dependencies
React, Vue, Svelte, Angular (SPA)	Static single-page application	None of the above (falls back to the SPA/static adapter)

Framework detection is automatic. To override it, set the framework prop explicitly:

new Hosting(stack, 'Web', {
  root: join(__dirname, '..'),
  framework: 'nextjs',
});

For the full list of supported framework versions and native platform clients, see Supported platforms.

Basic usage

Before you begin, make sure you have a CDK layer file (aws-blocks/index.cdk.ts) and a frontend app with a package.json in your project.

Add Hosting to your CDK layer file. At minimum, provide the root path to your frontend app and a buildCommand. Pass your backend stack as api to serve the frontend and API from the same domain.

// aws-blocks/index.cdk.ts
import * as cdk from 'aws-cdk-lib';
import { BlocksStack, Hosting } from '@aws-blocks/blocks/cdk';
import { join } from 'node:path';

const app = new cdk.App();
const blocksStack = await BlocksStack.create(app, 'my-stack', {
  backendHandlerPath: './index.handler.ts',
  backendCDKPath: './index.ts',
});

new Hosting(blocksStack, 'Web', {
  root: join(__dirname, '..'),
  buildCommand: 'npm run build',
  api: blocksStack,
});

Omit the api prop to deploy a static-only site with no backend. If you already built your app, omit buildCommand and Hosting deploys the existing output.

The Hosting construct exposes the resources it creates as public readonly members, so you can reference them elsewhere in your CDK layer:

Member	Description
bucket	The Amazon S3 bucket storing static assets.
distribution	The Amazon CloudFront distribution serving the site.
url	The public HTTPS URL of the deployed site.
ssrFunction	The primary SSR AWS Lambda function, when the framework uses SSR.
buildCacheBucket	The build-cache Amazon S3 bucket, when buildCache.enabled is true.
monitoringTopic	The Amazon SNS topic for Amazon CloudWatch alarms, when monitoring is enabled.

Custom domains

Configure a custom domain with the domain prop. Amazon CloudFront requires the ACM certificate to be in the us-east-1 AWS Region. This requirement applies regardless of where you deploy the rest of your stack.

You can set up a domain in two ways.

Amazon Route 53 (automatic) – provide a hostedZone you control. Hosting requests a DNS-validated ACM certificate and creates the A and AAAA alias records automatically:

new Hosting(blocksStack, 'Web', {
  root: join(__dirname, '..'),
  buildCommand: 'npm run build',
  api: blocksStack,
  domain: {
    domainName: 'app.example.com',
    hostedZone: 'example.com',
  },
});

To serve both an apex domain and its www subdomain, pass an array of domain names and set wwwRedirect:

domain: {
  domainName: ['example.com', 'www.example.com'],
  hostedZone: 'example.com',
  wwwRedirect: 'toApex',
}

Bring your own DNS (manual) – if you manage DNS outside Amazon Route 53, omit hostedZone and supply a pre-validated certificate in us-east-1. Hosting does not create DNS records. Instead, it outputs the Amazon CloudFront distribution domain name. Point a CNAME (or an ALIAS/ANAME record for an apex domain) at that domain name:

domain: {
  domainName: ['app.example.com'],
  certificate: myPreValidatedCert, // ACM certificate in us-east-1
}

Note

If you provide neither a hosted zone nor a certificate, synthesis fails fast with a MissingCertificateError rather than waiting on an unvalidated certificate at deploy time. A certificate outside us-east-1 fails with an InvalidCertificateRegionError.

SSR compute

For SSR frameworks, tune the AWS Lambda function that renders your server-side routes with the compute prop. Hosting ignores this prop for SPA and static deployments.

new Hosting(blocksStack, 'Web', {
  root: join(__dirname, '..'),
  buildCommand: 'npm run build',
  framework: 'nextjs',
  api: blocksStack,
  compute: {
    memorySize: 1024,
    timeout: cdk.Duration.seconds(30),
  },
});

Option	Default	Description
memorySize	512	AWS Lambda memory size, in MB.
timeout	30 seconds	AWS Lambda timeout. Accepts a cdk.Duration or a plain number of seconds.
reservedConcurrency	None	Reserved concurrent executions for the SSR AWS Lambda function.
imageOptimization.reservedConcurrency	None	Reserved concurrency for the image-optimization AWS Lambda function. Left unreserved by default so deployments succeed on fresh AWS accounts.
logRetention	Two weeks	Amazon CloudWatch log retention for the SSR AWS Lambda function.

Security

Hosting provides several controls for protecting your distribution.

WAF – enable AWS WAF with the waf prop to add managed protections and rate limiting. You can also associate an existing WebACL by ARN (the WebACL must be in us-east-1):

waf: {
  enabled: true,
  rateLimit: 1000, // requests per 5-minute window per IP
}

Content Security Policy – set contentSecurityPolicy to override the restrictive default Content-Security-Policy header:

contentSecurityPolicy: "default-src 'self'; img-src 'self' data:;",

Geo-restriction – use geoRestriction to restrict access by country. Configure the prop with a countries array of ISO country codes and a type that either allows only those countries or blocks them. For the exact type values, see the geoRestriction property in the Hosting package source code on GitHub.

Warning

Hosting writes values from backendConfig to /.blocks-sandbox/config.json and injects them into the BLOCKS_CONFIG AWS Lambda environment variable. Both locations are publicly accessible. Do not include secrets, API keys, or other sensitive configuration. For sensitive values, use AWS Systems Manager Parameter Store or AWS Secrets Manager and read them at runtime.

Operations

Hosting includes operational features to keep deployments observable and reliable.

Monitoring – Amazon CloudWatch alarms are enabled by default and cover Amazon CloudFront 5xx rates, SSR AWS Lambda errors and throttles, and revalidation failures. If you omit snsTopicArn, Hosting creates an Amazon SNS topic and exposes it as the construct’s monitoringTopic member. You can subscribe to this topic for notifications. Set monitoring: { enabled: false } to opt out.

Skew protection – enabled by default. During a rolling deployment, viewers who started a session continue to receive assets from the same build. This prevents asset mismatches. Set skewProtection: { enabled: false } to disable it.

Access logging – enable Amazon CloudFront access logs to a dedicated Amazon S3 bucket with the logging prop:

logging: { enabled: true, retentionDays: 90 },

Build cache – enable buildCache to preserve framework build caches (such as .next/cache) between deployments in an Amazon S3 bucket, reducing cold-build times in CI:

buildCache: { enabled: true },

Configuration reference

The following table summarizes the top-level Hosting properties. All properties except root are optional.

Property	Default	Description
root	—	Path to the frontend app root directory. Required.
buildCommand	None	Shell command to build the frontend during CDK synthesis. Omit if you pre-built the app.
framework	Auto-detected	Framework type. Overrides detection from package.json.
buildOutputDir	Auto-detected	Path to the build output directory.
basePath	None	URL prefix for the entire site (for example, /app).
api	None	Backend stack to proxy through the same domain (single-origin, no CORS).
backendConfig	None	Extra config merged into config.json. Publicly accessible, so do not include secrets.
compute	See SSR compute	AWS Lambda compute configuration for SSR frameworks.
domain	None	Custom domain configuration.
waf	Disabled	AWS WAF configuration.
priceClass	PRICE_CLASS_100	Amazon CloudFront price class.
geoRestriction	None	Country allow/block list for the distribution.
buildCache	Disabled	Amazon S3-backed framework build cache.
errorPages	None	Custom 404/500 HTML pages. Incompatible with SPA client-side routing.
logging	Disabled	Amazon CloudFront access logging.
monitoring	Enabled	Amazon CloudWatch alarms wired to an Amazon SNS topic.
skewProtection	Enabled	Cookie-based build pinning during rolling deployments.
retainOnDelete	false	Retain the Amazon S3 bucket when you delete the stack.

For the full construct API, adapter internals, and advanced configuration, see the Hosting package source code on GitHub.