Minisite

Minisite is a small TypeScript CLI for publishing one HTML file or a directory of static assets to a dedicated hostname in an existing AWS account. It provisions a private S3 origin, CloudFront with Origin Access Control, an ACM certificate, and Route 53 aliases through one Minisite-owned CloudFormation stack.

Prerequisites

• Node.js 22 or newer.
• AWS credentials available through the normal AWS SDK provider chain, or a named AWS profile selected with --profile.
• An existing public Route 53 hosted zone in the same account.
• A deployment hostname exactly one label below that zone, such as report.example.com for example.com.
• Permission to manage the CloudFormation, S3, CloudFront, ACM, and Route 53 resources described below.

Minisite always uses us-east-1. It does not create hosted zones, register domains, deploy apex domains, or adopt existing unmanaged resources.

Install from this repository

npm ci
npm run build
npm link
minisite --help

npm link is optional; every example can instead use node dist/cli.js in place of minisite.

Deploy

minisite deploy [--dry-run] [--profile <name>] <domain> <path>

Deploy a single HTML file as index.html:

minisite deploy report.example.com ./report.html

Mirror a directory without transforming its files or requiring index.html:

minisite deploy report.example.com ./dist

Minisite validates all local content before calling AWS. It then verifies the AWS identity and deterministic stack ownership, creates or reuses the stack, uploads every local file, deletes remote keys that are no longer present, and requests one CloudFront invalidation for /*. Upload failure prevents stale deletion and invalidation; deletion failure prevents invalidation.

Directory deployments include dotfiles and reject symbolic links, special files, and empty file trees. A single-file deployment accepts only .html or .htm.

Initial provisioning can take several minutes while ACM validates the certificate and CloudFront creates the distribution. Success means the AWS operations and invalidation request completed; Minisite does not independently probe public DNS, TLS, or HTTP reachability.

Minisite builds one checksummed manifest in memory before contacting AWS. It checks that manifest again before and during upload and before stale deletion or invalidation. If the source changes, deployment fails with the affected keys; some current objects may already have been overwritten, but no stale objects are deleted and no invalidation is requested. Changes made after a successful command naturally require another deployment.

Dry run

minisite deploy --dry-run report.example.com ./dist

A dry run performs local validation and read-only AWS calls. For a new site it discovers the hosted zone and validates the in-memory CloudFormation template. For an existing site it verifies ownership and reports the exact stale object set. It never creates a change set, stack, object, DNS record, or invalidation.

Destroy

minisite destroy [--dry-run] [--profile <name>] [--yes] <domain>

Interactive destruction is default-negative:

minisite destroy report.example.com

Use --yes in a noninteractive environment. It skips only confirmation; ownership and schema checks remain mandatory. destroy --dry-run reports the owned resources and bucket contents without prompting or mutating AWS.

Destroy empties the stack-owned bucket before asking CloudFormation to delete the stack. It can clean up ownership-verified rollback and delete-failed stacks. ACM's reusable DNS-validation CNAME may remain in the parent zone after deletion.

Authentication

Without --profile, Minisite leaves credentials unset on every SDK client so the current AWS SDK chain is used unchanged, including environment, AWS CLI login, IAM Identity Center, shared configuration, process, web-identity, and instance or container credentials.

With --profile <name>, Minisite resolves that exact shared profile for the invocation. The profile may use static credentials, role assumption, a credential process, IAM Identity Center, or AWS CLI login. Credentials and cached tokens are never copied into project files, logs, stack parameters, outputs, or tags.

Required AWS permissions

Minisite does not install an IAM policy. The caller needs a scoped set of actions covering:

• sts:GetCallerIdentity.
• Route 53 public hosted-zone listing and the record changes CloudFormation makes.
• CloudFormation template validation, stack creation/deletion, describe calls, tags, resources, events, and wait/status reads.
• S3 bucket configuration through CloudFormation plus object listing, upload, and deletion by the CLI.
• CloudFront distribution/OAC lifecycle and tagging through CloudFormation plus invalidation creation by the CLI.
• ACM certificate request, DNS validation, tagging, and deletion through CloudFormation.

Account-specific service-control policies and permission boundaries may impose additional restrictions. Avoid granting a broad wildcard policy solely for Minisite.

Development

npm run format
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run verify

npm run verify is the full local and CI gate. The normal suite is offline and uses no credentials. See development and testing for the source map, test seams, packaging checks, and the explicitly gated live lifecycle test.

The functional requirements remain the authoritative behavior and safety contract. The implementation blueprint records the architecture and delivery rationale.