React SPA (Single Page Application) Starter
This project is basically just create-react-app with AWS deployment options, CircleCI and a few other nice-to-haves in every project.
It started out with way more boilerplate, but I really minimized what's in it recently. To see the old, much more fleshed out version, check out the old branches.
Table of Contents
- Quick Start Guides
- Environment Configuration
- Build and Deployment
- Provisioning AWS Resources
Quick Start Guides
Set up the project
- Make sure you have modern versions of Node (>= 10.16.0) and npm (>= 6.9.0). Using nvm makes life easy.
- Clone this repo with
git clone https://github.com/ryanjyost/react-spa-starter.git <YOUR_PROJECT_NAME>
- You should see the app open up in your browser at
Deploy to an AWS S3 Bucket
- Setup an AWS account and the AWS CLI
- Copy the
.env-cmdrc.default.jsfile and name the new file
.env-cmdrc.js. This file will house all your secret and AWS environment variables.
- Add a unique
commonsection of your
- Create an S3 Bucket that will host your React app by running
npm run provision:basicin your terminal.
- Verify that the S3 Bucket was created in the CloudFormation
section of the AWS Console. The CloudFormation stack "basic" should have a
- Build and upload your app by running
npm run deploy:prod
- Visit the public URL of your S3 bucket (Find in AWS Console -> S3 -> Bucket -> Properties -> Static website hosting -> Endpoint) to see the deployed app
Add CircleCI Pipeline
This project comes with CircleCI just because it's easy and free for public repos.
- Fork this repository.
- Create an account on CircleCI and select your forked repo. See the docs for more detail.
- Go to the settings of your project in the CircleCI dashboard and add any environment variables needed for building
and deploying to your S3 Bucket (or other host if you're not using AWS). You'll probably need
AWS_SECRET_ACCESS_KEY(get these as IAM security creds with proper perms to uploa to S3),
- Push an update to master (like a console log you can see in the browser) and check your CircleCI dashboard. If all
went well, CircleCI should run two jobs...
test-cypressruns the boilerplate end-to-end tests. And if those pass...
deploy-prodruns unit tests and then builds the app for production and uploads the production build to your S3 bucket.
Note: create-react-app requires that environment variables begin with
REACT_APP_SecretKey if used within the app!
There are a few tools and methods in this app that help to make environment configuration and management easy.
To set your own private environment variables, copy the
.env-cmdrc.default.js file and name the new
.env-cmdrc.js. This file type is supported by env-cmd, a package that makes environment stuff pretty easy to manage and leverage.
- Each top-level property of the object exported from the
.env-cmdrc.jsis an environment option.
- To inject environment variables into scripts, prepend the script with
env-cmd -eand an environment name, e.g.
"build:prod": "env-cmd -e production npm run build"
- If you provide a comma-separated list of environment names instead of just one, you can merge multiple configs,
with the first listed config being overwritten by the second, etc. This makes using a
commonconfig object easy, e .g.
"build:prod": "env-cmd -e common,production npm run build"
This project uses Cypress for its E2E testing. Their docs and guides, as well as GitHub issue threads, are fantastic so consult those when unsure of something. Cypress comes with a great GUI to help write new tests, debugging and watching the test scripts run in an actual Chrome browser.
To open the GUI and run tests in a visible browser, run
npm run cypress.
To run the test suite in headless mode and generate raw results, run
npm run test.
Once the test suite completes, run
npm run test:report for a nice HTML report.
Check out package.json for the actual code/commands that are executed by these commands.
build- Generates a deployable package of files in the
build:prod- Build your React app to be delpoyed to the production environment
build:staging- Build your React app to be delpoyed to the staging environment
check:circular- Prints a list of circular dependencies in the app. CRA makes these a relative non-issue, but good to be aware of.
check:deps- Get a list of unused dependencies.
check:orphans- Finds files/components that aren't being imported anywhere in the project.
cypress- Runs Cypress test suite in headless mode.
cypress:circleci- Special way to start the app and run Cypress tests in CircleCI.
cypress:open- Opens the Cypress GUI for to run and develop tests.
uploadscripts for the production environment.
uploadscripts for the staging environment.
deps:clear- Remove your
node_modulesdirectory, helpful when having weird npm issues.
provision:basic- Create an S3 bucket that can host your React app.
provision:basic_with_staging- Create staging and production S3 buckets to host your app deployments.
provision:custom_domain- Creates an S3 Bucket, CloudFront Distribution and DNS records to host your React app at a custom domain (that's registered on AWS).
provision:custom_domain_with_staging- Creates production and staging S3 Buckets, CloudFront Distributions and DNS records to host your React app at a custom domain (that's registered on AWS) and staging subdomain.
start- Run the app. Defaults to "local" environment.
start:staging- Run the app with staging environment config.
start:prod- Run the app with production environment config.
test- Run unit test suite.
upload- Upload app build to an S3 Bucket.
upload:staging- Upload app build to your staging bucket
upload:prod- Upload app build to your production bucket.
Build and Deployment
Provisioning AWS Resources
Add gotchas and insights here as needed
This project was bootstrapped with Create React App.