Hosting Buckets



Hosting buckets are designed for serving static content, such as single-page applications or static websites. They distribute your content through a CDN with over 300 points of presence (PoPs) worldwide, ensuring low latency for your users. Hosting buckets are also secure by default, with automatic TLS.

If you need more control over the bucket's configuration, consider using a standard bucket instead.

Under the hood, a hosting bucket uses two main components:

  • An S3 bucket to store your assets.
  • A CloudFront CDN distribution to cache and serve your assets.

Basic usage

You can configure a hosting bucket by simply providing the path to the directory you want to upload.

This folder's contents are uploaded to the bucket on every deploy.

resources:
  myWebsite:
    type: 'hosting-bucket'
    properties:
      uploadDirectoryPath: ./dist
HostingBucketAPI reference
typeRequired
No description

Type: string "hosting-bucket"

properties.uploadDirectoryPathRequired

Path to the build output directory (e.g., dist, build, out).

Type: string

This folder's contents are uploaded to the bucket on every deploy.

properties.build

Build command that produces the files to upload (e.g., npm run build).

Type: HostingBucketBuild

Runs during the packaging phase, in parallel with other resources. Bundle size is shown in deploy logs.

properties.dev

Dev server command for local development (e.g., npm run dev, vite).

Type: HostingBucketBuild

Used by stacktape dev.

properties.excludeFilesPatterns

Glob patterns for files to skip during upload (relative to uploadDirectoryPath).

Type: Array of string

properties.hostingContentTypeDefault: static-website

Optimizes caching and routing for your type of frontend app.

Type: string ENUM

Possible values: astro-static-websitegatsby-static-websitenuxt-static-websitesingle-page-appstatic-websitesveltekit-static-website

  • single-page-app: For React, Vue, Angular, or any SPA built with Vite/Webpack. Enables client-side routing (e.g., /about serves index.html). HTML is never browser-cached; hashed assets (.js, .css) are cached forever.

  • static-website (default): For multi-page static sites. All files are CDN-cached but never browser-cached, so users always see the latest content after a deploy.

  • astro-static-website / sveltekit-static-website / nuxt-static-website: Framework-specific presets that cache hashed build assets (_astro/, _app/, _nuxt/) indefinitely while keeping HTML fresh.

  • gatsby-static-website: Gatsby-specific caching following their recommendations.

You can override any preset's behavior using fileOptions.

properties.customDomains

Custom domains (e.g., www.example.com). Stacktape auto-creates DNS records and TLS certificates.

Type: Array of DomainConfiguration

Your domain must be added as a Route53 hosted zone in your AWS account first.

properties.disableUrlNormalization

Disable clean URL normalization (e.g., /about → /about.html).

Type: boolean

properties.edgeFunctions

Run edge functions on CDN requests/responses (URL rewrites, auth, A/B testing).

Type: EdgeFunctionsConfig

  • onRequest: Before cache lookup and before forwarding to the bucket.
  • onResponse: Before returning the response to the client.
properties.errorDocument

Page to show for 404 errors (e.g., /error.html).

Type: string

properties.indexDocumentDefault: /index.html

Page served for requests to /.

Type: string

properties.injectEnvironment

Inject deploy-time values into HTML files as window.STP_INJECTED_ENV.VARIABLE_NAME.

Type: Array of EnvironmentVar

Useful for making API URLs, User Pool IDs, and other dynamic values available to your frontend JavaScript without rebuilding.

properties.writeDotenvFilesTo

Write deploy-time values to a .env file in the specified directory.

Type: string

Merges with existing .env content if the file already exists.

properties.useFirewall

Name of a web-app-firewall resource to protect this site. Must have scope: cdn.

Type: string

properties.fileOptions

Set HTTP headers (e.g., Cache-Control) for files matching specific patterns.

Type: Array of DirectoryUploadFilter

properties.routeRewrites

Route specific URL patterns to different origins (e.g., /api/* → a Lambda function).

Type: Array of CdnRouteRewrite

Evaluated in order; first match wins. Unmatched requests go to the bucket.

overrides

Escape hatch to modify the underlying CloudFormation resources Stacktape creates.

Type: Object

Use dot-notation paths to override specific properties on any child resource. Find resource logical IDs with stacktape stack-info --detailed.

overrides:
  MyDbInstance:
    Properties.StorageEncrypted: true

Hosting content type

You can specify the type of content you are hosting. Based on this, Stacktape will configure the HTTP headers of the uploaded files and the CDN behavior.

  • single-page-app: For React, Vue, Angular, or any SPA built with Vite/Webpack. Enables client-side routing (e.g., /about serves index.html). HTML is never browser-cached; hashed assets (.js, .css) are cached forever.

  • static-website (default): For multi-page static sites. All files are CDN-cached but never browser-cached, so users always see the latest content after a deploy.

  • astro-static-website / sveltekit-static-website / nuxt-static-website: Framework-specific presets that cache hashed build assets (_astro/, _app/, _nuxt/) indefinitely while keeping HTML fresh.

  • gatsby-static-website: Gatsby-specific caching following their recommendations.

You can override any preset's behavior using fileOptions.

resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      hostingContentType: single-page-app

Custom domains

You can use a custom domain for your hosting bucket. If you don't have one, you can register one through Stacktape.

If you already have a domain, you can either let Stacktape manage it (if you use AWS Route 53 for DNS) or use a third-party DNS provider.

For more details, see the Domains and Certificates page.

Using Stacktape to manage domains and certs

Your domain must be added as a Route53 hosted zone in your AWS account first.

resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      hostingContentType: single-page-app
      customDomains:
        - domainName: example.com

Using a 3rd-party DNS

To use a domain from a provider like GoDaddy or Cloudflare:

  1. Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
  2. Add the customDomains configuration to your hosting bucket, using the certificate ARN and disabling DNS record creation.
resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>
  1. After deploying, find the hosting bucket's domain name in the Stacktape Console.
  2. In your DNS provider's dashboard, create a CNAME or ALIAS record pointing to the hosting bucket's domain name.

Edge Lambda functions

You can run Lambda functions at the edge to customize the content that the CDN delivers. For more information, see the Edge Lambda Functions page.

  • onRequest: Before cache lookup and before forwarding to the bucket.
  • onResponse: Before returning the response to the client.
EdgeFunctionsConfigAPI referenceParent:HostingBucket or CdnRouteRewrite
onRequest

Name of an edge-lambda-function to run when the CDN receives a request (before cache lookup).

Type: string

Use to modify the request, add auth checks, or return an immediate response without hitting the origin.

onResponse

Name of an edge-lambda-function to run before returning the response to the client.

Type: string

Use to modify response headers, add security headers, or set cookies. Does not run if the origin returned a 400+ error or if onRequest already generated a response.

onOriginRequest

Name of an edge-lambda-function to run before forwarding to the origin (after cache miss).

Type: string

Only runs on cache misses. Use to modify the request before it reaches your origin.

Warning: Stacktape uses this trigger internally for bucket/web-service/API Gateway CDN setups. Overriding it may break default behavior. Only use if you know what you're doing.

onOriginResponse

Name of an edge-lambda-function to run after the origin responds (before caching).

Type: string

Modify the response before it's cached and returned. Changes are cached as if they came from the origin.

resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts

  myWebsite:
    type: hosting-bucket
    properties:
      edgeFunctions:
        onRequest: authFunction

Referenceable parameters

The following parameters can be easily referenced using $ResourceParam directive directive.

To learn more about referencing parameters, refer to referencing parameters.

name
  • AWS (physical) name of the bucket

  • Usage: $ResourceParam('<<resource-name>>', 'name')
arn
  • Arn of the bucket

  • Usage: $ResourceParam('<<resource-name>>', 'arn')
cdnDomain
  • Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnDomain')
cdnUrl
  • Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnUrl')
cdnCustomDomains
  • 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')
cdnCustomDomainUrls
  • 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')