Repository files navigation

Deploy React.js web apps generated withcreate-react-app. Automates deployment with the built-in bundler and serves it up viaNginx. See theintroductory blog post and entry inHeroku elements.

• 🚦Purpose
• ⚠️Requirements
• 🚀Quick Start
• 🛠Usage
  1. Generate a React app
  2. Make it a git repo
  3. Create the Heroku app
  4. Commit & deploy ♻️
  5. Continue Development
  6. Push to Github
  7. Testing
• 👓Customization
  • Procfile
  • Web server
    • Routing clean URLs
    • HTTPS-only
    • Proxy
  • Environment variables
    • Set vars on Heroku
    • Set vars for local dev
    • Compile-time vs Runtime
      • Compile-time config
      • Runtime config
    • using an Add-on's config
  • npm Private Packages
• 🕵️ Troubleshooting
• 📍Version compatibility
• 🏙Architecture

This buildpack deploys a React UI as a static web site. TheNginx web server provides optimum performance and security for the runtime. SeeArchitecture for details.

If your goal is to combine React UI + API (Node, Ruby, Python…) into asingle app, then this buildpack is not the answer. The simplest combined solution is all #"auto">▶️create-react-app + Node.js server on Heroku

Combination with other languages is possible too, likecreate-react-app + Rails 5 server.

• Heroku
  • command-line tools (CLI)
  • a free account
• git
• Node.js
• create-react-app
  • npm install -g create-react-app

Ensurerequirements are met, then execute the following in a terminal.

✏️Replace$APP_NAME with a name for your unique app.

create-react-app$APP_NAMEcd$APP_NAMEgit initheroku create$APP_NAME --buildpack https://github.com/mars/create-react-app-buildpack.gitgit add.git commit -m"Start with create-react-app"git push heroku masterheroku open

Once deployed,continue development 🌱

For explanation about these steps, continue reading thenext section.

create-react-app my-appcd my-app

• Ifyarn is installed locally, the new app will use it instead ofnpm.

git init

At this point, this new repo is local, only on your computer. Eventually, you may want topush to Github.

heroku create$APP_NAME --buildpack https://github.com/mars/create-react-app-buildpack.git

✏️Replace$APP_NAME with a name for your unique app.

This command:

• sets theapp name & its URLhttps://my-app-name.herokuapp.com
• sets thebuildpack to deploy acreate-react-app app
• configures theheroku remote in the local git repo, sogit push heroku master will push to this new Heroku app.

git add.git commit -m"Start with create-react-app"git push heroku master

heroku open

Find the app onyour dashboard.

Work with your app locally usingnpm start. See:create-react-app docs

Then, commit & deploy ♻️

Eventually, to share, collaborate, or simply back-up your code,create an empty repo at Github, and then follow the instructions shown on the repo topush an existing repository from the command line.

Usecreate-react-app's built-in Jest testing or whatever testing library you prefer.

Heroku CI is supported with minimal configuration. The CI integration is compatible with npm & yarn (seebin/test).

Heroku CI usesapp.json to provision test apps. To support Heroku CI, commit this minimal exampleapp.json:

{"buildpacks": [    {"url":"https://github.com/mars/create-react-app-buildpack"    }  ]}

Heroku apps may declare what processes are launched for a successful deployment by way of theProcfile. This buildpack's default process comes fromheroku/static buildpack. (See: 🏙Architecture). The implicitProcfile to start the static web server is:

web: bin/boot

To customize an app's processes, commit aProcfile and deploy. Includeweb: bin/boot to launch the default web process, or you may replace the default web process. Additionalprocess types may be added to run any number of dynos with whatever arbitrary commands you want, and scale each independently.

🚦If replacing the default web process, please check this buildpack'sPurpose to avoid misusing this buildpack (such as running a Node server) which can lead to confusing deployment issues.

The web server may beconfigured via the static buildpack.

The defaultstatic.json, if it does not exist in the repo, is:

{"root":"build/" }

React Router (not included) may easily use hash-based URLs likehttps://example.com/index.html#/users/me/edit. This is nice & easy when getting started with local development, but for a public app you probably want real URLs likehttps://example.com/users/me/edit.

Create astatic.json file to configure the web server for cleanbrowserHistory with React Router v3 &BrowserRouter with v4:

{"root":"build/","routes": {"/**":"index.html"  }}

👓 Seecustom routing w/ the static buildpack.

Enforce secure connections by automatically redirecting insecure requests tohttps://, instatic.json:

{"root":"build/","https_only":true}

Prevent downgrade attacks withHTTP strict transport security. Add HSTS"headers" tostatic.json:

{"root":"build/","https_only":true,"headers": {"/**": {"Strict-Transport-Security":"max-age=7776000"    }  }}

• max-age is the number of seconds to enforce HTTPS since the last connection; the example is 90-days

Proxy XHR requests from the React UI in the browser to API backends. Use to prevent same-origin errors whenCORS is not supported on the backend.

To make calls through the proxy, use relative URL's in the React app which will be proxied to the configured target URL. For the example URL prefix of/api/, here's how the proxy would rewrite the requests:

/api/search-items  → https://backend.example.com/search-items  /api/users/me  → https://backend.example.com/users/me

You may choose any prefix and may have multiple proxies with different prefixes.

Theheroku/static buildpack (see: 🏙Architecture) providesProxy Backends configuration to utilize Nginx for high-performance proxies in production.

Add"proxies" tostatic.json:

{"root":"build/","proxies": {"/api/": {"origin":"${API_URL}"    }  }}

Then, point the React UI app to a specific backend API:

heroku config:set API_URL="https://backend.example.com"

create-react-app itself provides a built-inproxy for development. This may be configured to match the behavior ofproxy for deployment.

Add"proxy" topackage.json:

{"proxy": {"/api": {"target":"http://localhost:8000","pathRewrite": {"^/api":"/"      }    }  }}

Replacehttp://localhost:8000 with the URL to your local or remote backend service.

REACT_APP_* environment variables are supported with this buildpack.

🤐Be careful not to export secrets. These values may be accessed by anyone who can see the React app.

heroku config:set REACT_APP_HELLO='I love sushi!'

Requires at least create-react-app 0.7. Earlier versions only support Compile-time.

Create a.env file that sets a variable per line:

REACT_APP_API_URL=http://api.example.comREACT_APP_CLIENT_ID=XyzxYzxyZ

Two versions of variables are supported. In addition to compile-time variables applied duringbuild the app supports variables set at runtime, applied as each web dyno starts-up.

♻️ The app must be re-deployed for compiled changes to take effect.

heroku config:set REACT_APP_HELLO='I love sushi!'git commit --allow-empty -m"Set REACT_APP_HELLO config var"git push heroku master

Requires at least create-react-app 0.7.

Install theruntime env npm package:

npm install @mars/heroku-js-runtime-env --save

Then, require/import it to use the vars within components:

importReact,{Component}from'react';importruntimeEnvfrom'@mars/heroku-js-runtime-env';classAppextendsComponent{render(){// Load the env object.constenv=runtimeEnv();// …then use values just like `process.env`return(<code>Runtime env var example:{env.REACT_APP_HELLO}</code>);}}

⚠️Avoid setting backslash escape sequences, such as\n, into Runtime config vars. Use literal UTF-8 values only; they will be automatically escaped.

🤐Be careful not to export secrets. These values may be accessed by anyone who can see the React app.

Use a custom.profile.d script to make variables visible to the React app by prefixing them withREACT_APP_.

1. create.profile.d/000-react-app-exports.sh

2. make it executablechmod +x .profile.d/000-react-app-exports.sh

3. add anexport line for each variable:

   export REACT_APP_ADDON_CONFIG=${ADDON_CONFIG:-}

4. set-up & useRuntime configuration to access the variables

For example, to use the API key for theFilestack JS image uploader:

export REACT_APP_FILEPICKER_API_KEY=${FILEPICKER_API_KEY:-}

Private modules are supported during build.

1. Setup your app with a.npmrc file followingnpm's guide for CI/deployment.

2. Set your secret in theNPM_TOKEN config var:

   heroku config:set NPM_TOKEN=xxxxx

1. Confirm that your app is using this buildpack:

   heroku buildpacks

   If it's not usingcreate-react-app-buildpack, then set it:

   heroku buildpacks:set https://github.com/mars/create-react-app-buildpack.git

   …and deploy with the new buildpack:

   git commit --allow-empty -m'Switch to create-react-app-buildpack'git push heroku master

   If the error still occurs, then at least we know it's really using this buildpack! Proceed with troubleshooting.

2. Check this README to see if it already mentions the issue.

3. Search ourissues to see if someone else has experienced the same problem.

4. Search the internet for mentions of the error message and its subject module, e.g.ENOENT "node-sass"

5. File a newissue. Please include:

   • build log output
   • link to GitHub repo with the source code (if private, grant read access to @mars)

This buildpack will never intentionally cause previously deployed apps to become undeployable. Using masteras directed in the main instructions will always deploy an app with the most recent version of this buildpack.

Releases are tagged, so you can lock an app to a specific version, if that kind of determinism pleases you:

heroku buildpacks:set https://github.com/mars/create-react-app-buildpack.git#v1.2.1

✏️Replacev1.2.1 with the desiredrelease tag.

♻️ Then, commit & deploy to rebuild on the new buildpack version.

This buildpack combines several buildpacks, specified in.buildpacks, to supportzero-configuration deployment on Heroku:

1. heroku/nodejs buildpack
   • installs completenode, puts it on the$PATH
   • version specified inpackage.json,engines.node
   • node_modules/ cached between deployments
2. mars/create-react-app-inner-buildpack
   • production build for create-react-app
   • generates thedefaultstatic.json
   • enablesruntime environment variables
3. heroku/static buildpack
   • Nginx web server
   • launches viabin/boot
   • configure viastatic.json; seeoptions specific to this buildpack andall options

Runtime processes are launched based on the last buildpack's default processes, the static buildpack's Nginx web server. Processes may be customized with aProcfile.

Some kind feedback pointed out that this buildpack is not necessarily specific tocreate-react-app.

This buildpack can deploy any SPA [single-page app] as long as it meets the following requirements:

• npm run build performs the transpile/bundling
• the filebuild/index.html orthe root specified instatic.json exists at runtime.