Skip to main content

ReactStaticSite

caution

This is the SST v0.x Constructs doc. SST v1 is now released. If you are using v1, see the v1 Constructs doc. If you are looking to upgrade to v1, check out the migration steps.

The ReactStaticSite construct is a higher level CDK construct that makes it easy to create a React single page app. It provides a simple way to build and deploy the site to an S3 bucket; setup a CloudFront CDN for fast content delivery; and configure a custom domain for the website URL.

It's designed to work with static sites built with Create React App. It also allows you to automatically set environment variables in your React app directly from the outputs of your SST app.

The ReactStaticSite construct internally extends the StaticSite construct with the following pre-configured defaults.

Initializer

new ReactStaticSite(scope: Construct, id: string, props: StaticSiteProps)

Parameters

Examples

The ReactStaticSite construct is designed to make it easy to work with React apps created using Create React App or similar projects.

Creating a React app

Deploys a React app in the path/to/src directory.

new ReactStaticSite(this, "ReactSite", {
path: "path/to/src",
});

Configuring environment variables

The ReactStaticSite construct allows you to set the environment variables in your React app based on outputs from other constructs in your SST app. So you don't have to hard code the config from your backend. Let's look at how.

Create React App supports setting build time environment variables. In your JS files this looks like:

src/App.js
console.log(process.env.REACT_APP_API_URL);
console.log(process.env.REACT_APP_USER_POOL_CLIENT);

And in your HTML files:

public/index.html
<p>Api endpoint is: %REACT_APP_API_URL%</p>

You can pass these in directly from the construct.

new ReactStaticSite(this, "ReactSite", {
path: "path/to/src",
environment: {
REACT_APP_API_URL: api.url,
REACT_APP_USER_POOL_CLIENT: auth.cognitoUserPoolClient.userPoolClientId,
},
});

Where api.url or auth.cognitoUserPoolClient.userPoolClientId are coming from other constructs in your SST app.

While deploying

On sst deploy, the environment variables will first be replaced by placeholder values, {{ REACT_APP_API_URL }} and {{ REACT_APP_USER_POOL_CLIENT }}, when building the React app. And after the referenced resources have been created, the Api and User Pool in this case, the placeholders in the HTML and JS files will then be replaced with the actual values.

While developing

To use these values while developing, run sst start to start the Live Lambda Development environment.

npx sst start

Then in your React app to reference these variables, add the sst env command.

package.json
"scripts": {
"start": "sst env \"react-scripts start\"",
"build": "react-scripts build",
"test": "react-scripts test",
"eject": "react-scripts eject"
},

Now you can start your React app as usualy and it'll have the environment variables from your SST app.

npm run start

There are a couple of things happening behind the scenes here:

  1. The sst start command generates a file with the values specified by ReactStaticSite's environment prop.
  2. The sst env CLI will traverse up the directories to look for the root of your SST app.
  3. It'll then find the file that's generated in step 1.
  4. It'll load these as environment variables before running the start command.
note

sst env only works if the React app is located inside the SST app or inside one of its subdirectories. For example:

/
sst.json
react-app/

Configuring custom domains

You can also configure custom domains for your React app. SST supports domains that are shoted either on Route 53 or externally.

Using the basic config for a domain hosted on Route 53.

new ReactStaticSite(this, "ReactSite", {
path: "path/to/src",
customDomain: "domain.com",
});

For more custom domain examples, check out the StaticSite examples.

Properties

Refer to the properties in the StaticSite construct.