StaticSiteV2

The StaticSiteV2 component lets you deploy a static website to Cloudflare. It uses Cloudflare Workers with static assets to serve your files.

It can also build your site by running your static site generator, like Vite and uploading the build output as static assets.

Minimal example

Simply uploads the current directory as a static site.

new sst.cloudflare.StaticSiteV2("MyWeb");

Change the path

Change the path that should be uploaded.

new sst.cloudflare.StaticSiteV2("MyWeb", {
  path: "path/to/site"
});

Deploy a Vite SPA

Use Vite to deploy a React/Vue/Svelte/etc. SPA by specifying the build config.

new sst.cloudflare.StaticSiteV2("MyWeb", {
  build: {
    command: "npm run build",
    output: "dist"
  },
  notFound: "single-page-application"
});

Deploy a Jekyll site

Use Jekyll to deploy a static site.

new sst.cloudflare.StaticSiteV2("MyWeb", {
  build: {
    command: "bundle exec jekyll build",
    output: "_site"
  }
});

Add a custom domain

Set a custom domain for your site.

new sst.cloudflare.StaticSiteV2("MyWeb", {
  domain: "my-app.com"
});

Set environment variables

Set environment variables for the build process of your static site. These will be used locally and on deploy.

For some static site generators like Vite, environment variables prefixed with VITE_ can be accessed in the browser.

const bucket = new sst.cloudflare.Bucket("MyBucket");

new sst.cloudflare.StaticSiteV2("MyWeb", {
  environment: {
    BUCKET_NAME: bucket.name,
    // Accessible in the browser
    VITE_STRIPE_PUBLISHABLE_KEY: "pk_test_123"
  },
  build: {
    command: "npm run build",
    output: "dist"
  }
});

---

Constructor

new StaticSiteV2(name, args?, opts?)

Parameters

• name string

• args? StaticSiteV2Args

• opts? ComponentResourceOptions

StaticSiteV2Args

build?

Type Input<Object>

• command

• output

Configure if your static site needs to be built. This is useful if you are using a static site generator.

The build.output directory will be uploaded as static assets.

For a Vite project using npm this might look like this.

{
  build: {
    command: "npm run build",
    output: "dist"
  }
}

build.command

Type Input<string>

The command that builds the static site. It’s run before your site is deployed. This is run at the root of your site, path.

{
  build: {
    command: "yarn build"
  }
}

build.output

Type Input<string>

The directory where the build output of your static site is generated. This will be uploaded.

The path is relative to the root of your site, path.

{
  build: {
    output: "build"
  }
}

dev?

Type false | Object

• autostart?

• command?

• directory?

• title?

• url?

Configure how this component works in sst dev.

Note

In sst dev your static site is run in dev mode; it’s not deployed.

Instead of deploying your static site, this starts it in dev mode. It’s run as a separate process in the sst dev multiplexer. Read more about sst dev.

To disable dev mode, pass in false.

Use a custom dev command.

{
  dev: {
    command: "yarn dev"
  }
}

dev.autostart?

Type Input<boolean>

Default true

Configure if you want to automatically start this when sst dev starts. You can still start it manually later.

dev.command?

Type Input<string>

Default “npm run dev”

The command that sst dev runs to start this in dev mode.

dev.directory?

Type Input<string>

Default Uses the path

Change the directory from where the command is run.

dev.title?

Type Input<string>

The title of the tab in the multiplexer.

dev.url?

Type Input<string>

Default “http://url-unavailable-in-dev.mode”

The url when this is running in dev mode.

Since this component is not deployed in sst dev, there is no real URL. But if you are using this component’s url or linking to this component’s url, it can be useful to have a placeholder URL. It avoids having to handle it being undefined.

domain?

Type Input<string>

Set a custom domain for your static site. Supports domains hosted on Cloudflare.

Tip

You can migrate an externally hosted domain to Cloudflare by following this guide.

{
  domain: "domain.com"
}

environment?

Type Input<Record<string, Input<string>>>

Set environment variables for your static site. These are made available:

1. Locally while running your site through sst dev.
2. In the build process when running build.command.

environment: {
  API_URL: api.url
  STRIPE_PUBLISHABLE_KEY: "pk_test_123"
}

Some static site generators like Vite have their concept of environment variables, and you can use this option to set them.

Note

The types for the Vite environment variables are generated automatically. You can change their location through vite.types.

These can be accessed as import.meta.env in your site. And only the ones prefixed with VITE_ can be accessed in the browser.

environment: {
  API_URL: api.url
  // Accessible in the browser
  VITE_STRIPE_PUBLISHABLE_KEY: "pk_test_123"
}

notFound?

Type Input<“single-page-application” | “404”>

Default “single-page-application”

Configure the response when a request does not match a static asset.

• "single-page-application": Serve index.html for unmatched routes (SPA mode)
• "404": Serve the nearest 404.html file with a 404 status

path?

Type Input<string>

Default ”.”

Path to the directory where your static site is located. By default this assumes your static site is in the root of your SST app.

This directory will be uploaded as static assets. The path is relative to your sst.config.ts.

Note

If the build options are specified, build.output will be uploaded as static assets instead.

If you are using a static site generator, like Vite, you’ll need to configure the build options. When these are set, the build.output directory will be uploaded as static assets instead.

Change where your static site is located.

{
  path: "packages/web"
}

trailingSlash?

Type “drop” | “auto” | “force”

Default “auto”

Configure trailing slash behavior for HTML pages.

• "auto": Individual files served without slash, folder indexes with slash
• "force": All HTML pages served with trailing slash
• "drop": All HTML pages served without trailing slash

Force trailing slashes

{
  trailingSlash: "force"
}

transform?

Type Object

• server?

Transform how this component creates its underlying resources.

transform.server?

Type WorkerArgs | (args: WorkerArgs, opts: ComponentResourceOptions, name: string) => void

Transform the Worker component used for serving the static site.

Properties

nodes

Type Object

• server

The underlying resources this component creates.

nodes.server

Type undefined | Worker

The worker that serves the requests.

url

Type Output<undefined | string>

The URL of the website.

If the domain is set, this is the URL with the custom domain. Otherwise, it’s the auto-generated worker URL.

SDK

Use the SDK in your runtime to interact with your infrastructure.

---

Links

This is accessible through the Resource object in the SDK.

• url undefined | string

  The URL of the website.

  If the domain is set, this is the URL with the custom domain. Otherwise, it’s the auto-generated worker URL.