ReactStaticSite

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 a React app built using Create React App. It also allows you to automatically set the environment variables in your React app directly from the outputs in 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: ReactStaticSiteProps)

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 package.

npm install --save-dev @serverless-stack/static-site-env

And tweak the React start script to:

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.jon
react-app/

Configuring custom domains#

You can also configure custom domains for your React app. SST currently supports domains that are configured using Route 53. If your domains are hosted elsewhere, you can follow this guide to migrate them to Route 53.

Using the basic config.

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.

ReactStaticSiteProps#

Takes the following construct props in addition to all the StaticSiteProps.

path#

Type : string

Path to the directory where the React app is located.

environment#

Type : { [key: string]: string }

An associative array with the key being the React environment variable name. Environment variables must start with REACT_APP_, as these are the ones loaded by Create React App.

{
REACT_APP_API_URL: api.url
}