A Stacktape hosting-bucket deploys static frontend files to S3 and serves them through a CloudFront CDN. Use it for static sites, SPAs, and pre-rendered framework outputs where the deploy artifact is a directory of HTML, CSS, JavaScript, images, and other assets rather than a server process.
When to use
A hosting-bucket is the best fit when your frontend build produces static files that can be uploaded as-is. Stacktape runs the optional build command, uploads the configured output directory on every deploy, and applies content presets for browser caching, CDN caching, and routing behavior.
- Vite, React, Vue, Angular, or similar SPAs — use the
single-page-apppreset so client-side routes like/aboutserveindex.html. - Static marketing sites or documentation — use the default
static-websitepreset for multi-page sites where HTML should stay fresh after each deploy. - Static Astro, SvelteKit, Nuxt, or Gatsby output — use the framework-specific preset so hashed build assets can be cached longer while HTML remains fresh.
- Frontend-only apps that need deploy-time values — use
injectEnvironmentorwriteDotenvFilesToto pass values such as API URLs or User Pool IDs without rebuilding after deployment.
When NOT to use
- Server-rendered frontend apps — use Next.js, Astro, Nuxt, SvelteKit, SolidStart, TanStack Start, or Remix when the app needs a server runtime.
- Public APIs or backend services — use a web-service, Lambda function, or HTTP API Gateway instead of trying to serve dynamic responses from static hosting.
- Large object storage without a website — use an S3 bucket when you need object storage rather than a CDN-backed website.
- Advanced CDN-only routing — use a dedicated CDN when the primary concern is routing multiple origins rather than hosting one static site with optional rewrites.
Basic example
This example builds a Vite-style frontend, uploads the dist directory, and uses the single-page-app preset so browser routes are handled by the frontend app.
uploadDirectoryPath points at the directory Stacktape uploads on every deploy. The optional build.command runs during packaging, and the optional dev.command is used by stacktape dev. The single-page-app preset is the important choice for React, Vue, Angular, and other client-routed apps.
Build and dev
A hosting-bucket can run one command for deployment builds and a separate command for dev mode. Both commands use the same HostingBucketBuild shape: a required command and an optional workingDirectory, which defaults to the project root when omitted. Commands run through the system shell, so npm ci && npm run build works as written. When workingDirectory has its own package.json, Stacktape installs that directory's dependencies before the build.
Use build when your static files are generated from source code. Skip build when uploadDirectoryPath already contains the files you want to upload, such as a directory produced by an external CI job. Use dev to tell stacktape dev which frontend development server command to run.
workingDirectory is useful in monorepos where the frontend package is not at the Stacktape project root. Keep the build output path aligned with the command: uploadDirectoryPath should point to the directory produced by the build command, not the source directory.
Content presets
hostingContentType selects the caching and routing preset for the static site. The default is static-website; other supported presets are single-page-app, astro-static-website, sveltekit-static-website, nuxt-static-website, and gatsby-static-website.
| Preset | Best fit | Source-grounded behavior |
|---|---|---|
static-website | Multi-page static sites | CDN-caches files but avoids browser-caching so users see current content after deploys. |
single-page-app | React, Vue, Angular, Vite, Webpack SPAs | Serves index.html for client-side routes and caches hashed .js and .css assets indefinitely. |
astro-static-website | Static Astro output | Caches hashed _astro/ assets indefinitely while keeping HTML fresh. |
sveltekit-static-website | Static SvelteKit output | Caches hashed _app/ assets indefinitely while keeping HTML fresh. |
nuxt-static-website | Static Nuxt output | Caches hashed _nuxt/ assets indefinitely while keeping HTML fresh. |
gatsby-static-website | Gatsby static output | Uses Gatsby-specific caching behavior following Gatsby recommendations. |
Use fileOptions when a preset is close but not exact. The source exposes fileOptions for setting HTTP headers such as Cache-Control on files matching specific patterns, so keep custom rules narrow and let the preset handle the rest.
indexDocument controls the page served for / and defaults to /index.html. errorDocument sets the page shown for 404 errors — /404.html in the example above is only an example; set errorDocument to the path of the error page in your uploaded output directory. disableUrlNormalization is available when you do not want clean URL normalization such as /about resolving to /about.html.
Custom domains
A hosting-bucket can serve static content from custom domains such as www.example.com. By default, Stacktape creates DNS records and provisions TLS certificates for configured domains; set disableDnsRecordCreation when DNS is managed elsewhere. The domain must already be added as a Route53 hosted zone in the AWS account.
For most sites, prefer the default DNS-record and certificate behavior because it keeps the Stacktape config small. Set customCertificateArn only when you need to use a specific ACM certificate, and set disableDnsRecordCreation when DNS records are managed outside Stacktape, such as through another DNS provider.
Environment injection
A hosting-bucket can expose deploy-time values to frontend code without requiring another frontend build. injectEnvironment writes values into HTML files as window.STP_INJECTED_ENV.VARIABLE_NAME, while writeDotenvFilesTo writes deploy-time values into a .env file in the specified directory.
Use injectEnvironment for values that the browser reads at runtime from HTML. Use writeDotenvFilesTo when you want Stacktape to write deploy-time values to a .env file in the specified directory; existing .env content is merged if present.
In dev mode, stacktape dev resolves injectEnvironment and passes the values to the dev.command server as environment variables. A $ResourceParam of a function or container resolves to the URL that dev mode runs it at. The values are also written to .env.local in the dev workingDirectory (the project root by default), inside a block between # >>> stacktape dev and # <<< stacktape dev <<< marker lines. Each start rewrites only that block, so your own lines in the file stay. The block names the stage that wrote it: while that stage's dev session runs the app, a dev session of another stage in the same directory leaves the block unchanged and passes its own values only as environment variables. Nothing else is written there: a hosting bucket has no connectTo, so database connection details and passwords never reach the frontend.
Bundlers expose only prefixed variables to browser code, for example VITE_ in Vite. Name the variables accordingly, such as VITE_API_URL: $ResourceParam('api', 'url'), and read them with import.meta.env.VITE_API_URL.
Routing
routeRewrites routes specific URL patterns to different origins, for example /api/* to a Lambda function. Rewrites are evaluated in order; unmatched requests go to the bucket. See the API reference for the exact CdnRouteRewrite fields.
Use route rewrites when a mostly static frontend needs a small number of backend paths under the same site hostname. Skip rewrites when the backend deserves its own API domain or when you are already using a server-rendered frontend resource that owns routing.
Edge functions
A hosting-bucket can attach edge functions to CDN requests and responses for URL rewrites, authentication checks, A/B testing, or response changes. onRequest runs before the CDN cache lookup and before forwarding to the bucket; onResponse runs before returning the response to the client.
Use edge functions for small request or response decisions that must happen at the CDN layer. Keep application logic in a Lambda function or backend service when the code needs normal backend dependencies, persistent state, or easier debugging. Edge code changes can make caching and routing harder to reason about, so most static sites should start without edge functions. The exact EdgeFunctionsConfig shape — including onRequest and onResponse sub-properties — is in the API reference below.
Firewall
A hosting-bucket can reference a web application firewall by name through useFirewall. The referenced firewall must be a web-app-firewall resource with scope: cdn, because the hosting-bucket is protected at the CDN layer.
Enable a firewall for public static sites that need request filtering at the edge, especially when the same CDN hostname also routes API paths through routeRewrites. Skip it for low-risk internal previews and simple static pages where the default CDN behavior is enough. Keep the constraint scoped: hosting-bucket.useFirewall attaches a CDN-scoped firewall to this static site.
File uploads
A hosting-bucket uploads the configured output directory on every deploy, and excludeFilesPatterns can skip files relative to uploadDirectoryPath. Use exclusion patterns for sourcemaps, local-only files, or generated artifacts that should not become public website objects.
Because static hosting publishes uploaded files through the CDN, use excludeFilesPatterns to avoid uploading known unwanted files; do not rely on a static-site output directory as a place to hold secrets.
Static Hosting FAQ
Which build output directory should I upload?
Set uploadDirectoryPath to the directory produced by your frontend build, such as dist, build, or out. Stacktape uploads that directory's contents on every deploy. If your build runs in a subdirectory, set build.workingDirectory and keep uploadDirectoryPath pointed at the resulting output folder.
Which hostingContentType should I choose?
Use single-page-app for React, Vue, Angular, Vite, or Webpack apps with client-side routing — it serves index.html for routes like /about so browser refreshes and direct links work, and caches hashed assets indefinitely. Use the default static-website for ordinary multi-page sites, and use the framework-specific presets for static Astro, SvelteKit, Nuxt, or Gatsby outputs.
Why does my custom domain fail to provision?
customDomains only works if the domain already exists as a Route53 hosted zone in the AWS account — Stacktape creates the DNS records and TLS certificate but does not register the zone for you. If DNS is managed elsewhere, set disableDnsRecordCreation, and set customCertificateArn to use a specific ACM certificate. For broader domain concepts, see custom domains.
Can static hosting inject environment variables without rebuilding?
Yes. injectEnvironment exposes deploy-time values in HTML files as window.STP_INJECTED_ENV.VARIABLE_NAME, and writeDotenvFilesTo writes values to a .env file in a target directory (merging existing content) — both without a second frontend build. Use this for public frontend configuration such as API URLs, not for browser-inaccessible secrets. See secrets for secret management.
How much does S3 and CloudFront static hosting cost?
A hosting-bucket bills through the underlying AWS services it provisions — S3 storage and requests, plus CloudFront data transfer and CDN features — so cost scales with traffic and stored assets rather than a fixed price. Use cost dashboards after deployment to inspect actual stack spend.
Static hosting vs S3 bucket: which should I use?
Use static hosting when you want a website: build command, upload directory, CDN behavior, content presets, custom domains, and frontend environment injection. Use an S3 bucket when you need general object storage for application data, uploads, backups, or private files.
Can I route API requests from a static site?
Yes, routeRewrites routes specific URL patterns to different origins — for example, /api/* to a Lambda function — while unmatched requests go to the bucket. Rewrites are evaluated in order. See the API reference for the exact CdnRouteRewrite fields. For larger APIs, define the backend explicitly with HTTP API Gateway, Lambda functions, or web services.
API Reference
HostingBucketPropsReferenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
AWS (physical) name of the bucket
- Usage:
$ResourceParam('<<resource-name>>', 'name')
Arn of the bucket
- Usage:
$ResourceParam('<<resource-name>>', 'arn')
Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnDomain')
Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnUrl')
Comma-separated list of custom domain names assigned to the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomains')
Comma-separated list of custom domain name URLs of the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomainUrls')