wirejs-deploy-cdk

Experimental: WireJS is an experimental hobby project and is not production software. For a professionally supported project in a similar spirit, see AWS Blocks, which benefits from lessons and ideas explored here.

CDK-based deployment provider for wirejs apps. Deploys your wirejs app to AWS using:

• AWS Lambda for API and SSR handling
• Amazon S3 for static assets
• Amazon CloudFront for hosting (CDN, SSL, optional custom domains)
• Amazon DynamoDB for distributed tables
• Amazon Cognito for authentication (if used)
• GitHub Actions for CI/CD

Setup

Run the scaffolding CLI to set up your project for CDK deployment:

npm create wirejs-deploy-cdk

Then follow the instructions to configure GitHub Actions with the required AWS credentials.

Guided Setup Commands

You can run guided setup directly from this package:

npx wirejs-deploy-cdk github

Configures GitHub Actions AWS OIDC integration by walking you through:

• OIDC identity provider creation (if missing)
• IAM role creation/update with trust policy for your repo refs
• Optional role policy attach
• Optional GitHub Actions secret setup via gh

npx wirejs-deploy-cdk setup

Runs the GitHub setup wizard and then optionally launches the domain setup wizard.

For custom domains only:

npx wirejs-deploy-cdk domain

Version-locked docs

When working in an installed app, prefer the README installed with that app's exact dependency version:

node -e "console.log(require.resolve('wirejs-deploy-cdk/package.json').replace(/package\.json$/, 'README.md'))"

The npm page is useful for browsing, but may not match the version installed in your app: https://www.npmjs.com/package/wirejs-deploy-cdk

deployment-config.ts

CDK deployment reads the app's top-level deployment-config.ts. This is the shared WireJS deployment configuration surface, also read by wirejs-scripts for build-time behavior. The CDK provider currently implements the AWS mapping for runtime/build preferences, custom domains, redirects, and Route53 DNS records. During deploy, the CLI copies the app into an OS temp directory outside node_modules, copies thin handler wrappers from assets/, and rewrites provider packages for the Lambda build: installed CLI runs use npm package specs, while local workspace runs use packed tarballs, including the local wirejs-resources package as wirejs-resources-base, so the generated lockfile includes matching transitive runtime dependencies for CDK Lambda bundling. The copied app lockfile is removed after dependency rewrites so npm cannot keep pre-deploy package resolutions such as the local/base wirejs-resources runtime in the Lambda asset.

import { DeploymentConfig } from 'wirejs-resources';

export default {
	runtimeDesiredMemoryMB: 1024,
	runtimeTimeoutSeconds: 30,
	runtimeNodeVersion: 22,
	bundleNodeModules: ['jsdom'],
	bundleFormat: 'esm',
	bundleMinify: true,
} satisfies DeploymentConfig;

Common runtime/build fields:

• runtimeDesiredMemoryMB
• runtimeTimeoutSeconds
• runtimeNodeVersion
• bundleNodeModules
• bundleFormat
• bundleMinify
• ssgExternalModules
• functionUrlAuthType

Custom domains

Custom domains are part of the general DeploymentConfig model. The CDK provider implements them with CloudFront aliases, ACM certificates, and Route53 records.

If you do not configure domains, deployments still work using generated CloudFront URLs.

To use custom domains, run the domain setup wizard before the first custom-domain deployment:

npx wirejs-deploy-cdk domain

Then configure domainsByBranch:

import { DeploymentConfig } from 'wirejs-resources';

export default {
	domainsByBranch: {
		main: 'staging.example.com',
		prod: 'www.example.com',
		'*': '{branch}.example.com',
	},
} satisfies DeploymentConfig;

With the default workflow model:

• main deploys to staging.example.com
• release/prod deploys to www.example.com
• release/foo deploys to foo.example.com

{branch} is replaced with a slug derived from the active branch/lane.

Redirects

Host redirects are configured in deployment-config.ts and apply whenever their target domain is deployed.

export default {
	domainsByBranch: {
		prod: 'www.example.com',
		'*': '{branch}.example.com',
	},
	redirects: [
		{ from: 'example.com', to: 'www.example.com', mode: 'permanent' },
		{ from: 'help.example.com', to: 'support.example.com' },
		{ from: '{branch}.old.example.com', to: '{branch}.new.example.com' },
	],
} satisfies DeploymentConfig;

Behavior:

• redirects are host-based and preserve path/query;
• mode: 'temporary' is the default and uses HTTP 307;
• mode: 'permanent' uses HTTP 308;
• redirect source hosts are included in aliases/certificates;
• from and to support {branch} substitution.

Route53 DNS records

DNS records are part of the general DeploymentConfig model. The CDK provider implements dnsRecordsByBranch with Route53. This is useful when migrating a zone into CDK management or when branch-specific verification records are needed.

export default {
	domainsByBranch: {
		main: 'www.example.com',
		'*': '{branch}.example.com',
	},
	dnsRecordsByBranch: {
		main: [
			{ name: '@', zoneDomain: 'example.com', type: 'MX', values: ['1 aspmx.l.google.com.'] },
			{ name: '@', zoneDomain: 'example.com', type: 'TXT', values: ['"v=spf1 include:_spf.google.com ~all"'] },
		],
		'*': [
			{ name: '_verify.{branch}', zoneDomain: 'example.com', type: 'TXT', values: ['"ok-{branch}"'] },
		],
	},
} satisfies DeploymentConfig;

Notes:

• supported record types: A, AAAA, CAA, CNAME, MX, NS, PTR, SPF, SRV, TXT;
• default TTL is 300 seconds unless ttlSeconds is set;
• FQDN names auto-resolve hosted zones;
• relative names such as @, www, or _dmarc require zoneDomain;
• {branch} substitution works in names, zones, and values;
• do not define A/AAAA records for hosts already managed by domainsByBranch.

Custom-domain requirements

• A Route53 hosted zone must exist for the root domain.
• Run npx wirejs-deploy-cdk domain to bootstrap hosted-zone and registrar/nameserver configuration.
• ACM certificates are created and DNS-validated automatically.
• First deployment may require a few minutes for DNS propagation.