Deploy React.js web apps generated with create-react-app. Automates deployment with the built-in bundler and serves it up via Nginx. See the introductory blog post and entry in Heroku elements.
- π¦ Purpose
β οΈ Requirements- π Quick Start
- π Usage
- π Customization
- π΅οΈ Troubleshooting
- π Version compatibility
- π Architecture
This buildpack deploys a React UI as a static web site. The Nginx web server provides optimum performance and security for the runtime. See Architecture for details.
If your goal is to combine React UI + API (Node, Ruby, Pythonβ¦) into a single app, then this buildpack is not the answer. The simplest combined solution is all javascript:
Combination with other languages is possible too, like create-react-app + Rails 5 server.
- Heroku
- git
- Node.js
- create-react-app
npm install -g create-react-app
Ensure requirements are met, then execute the following in a terminal.
βοΈ Replace $APP_NAME
with a name for your unique app.
create-react-app $APP_NAME
cd $APP_NAME
git init
heroku create $APP_NAME --buildpack https://github.com/mars/create-react-app-buildpack.git
git add .
git commit -m "Start with create-react-app"
git push heroku master
heroku open
Once deployed, continue development π±
For explanation about these steps, continue reading the next section.
create-react-app my-app
cd my-app
git init
At this point, this new repo is local, only on your computer. Eventually, you may want to push 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 the app name & its URL
https://my-app-name.herokuapp.com
- sets the buildpack to deploy a
create-react-app
app - configures the
heroku
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 on your dashboard.
Work with your app locally using npm 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 to push an existing repository from the command line.
Use create-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 (see bin/test
).
Heroku CI uses app.json
to provision test apps. To support Heroku CI, commit this minimal example app.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 the Procfile
. This buildpack's default process comes from heroku/static
buildpack. (See: π Architecture). The implicit Procfile
to start the static web server is:
web: bin/boot
To customize an app's processes, commit a Procfile
and deploy. Include web: bin/boot
to launch the default web process, or you may replace the default web process. Additional process 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's Purpose to avoid misusing this buildpack (such as running a Node server) which can lead to confusing deployment issues.
The web server may be configured via the static buildpack.
The default static.json
, if it does not exist in the repo, is:
{ "root": "build/" }
React Router (not included) may easily use hash-based URLs like https://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 like https://example.com/users/me/edit
.
Create a static.json
file to configure the web server for clean browserHistory
with React Router v3 & BrowserRouter
with v4:
{
"root": "build/",
"routes": {
"/**": "index.html"
}
}
π See custom routing w/ the static buildpack.
Enforce secure connections by automatically redirecting insecure requests to https://, in static.json
:
{
"root": "build/",
"https_only": true
}
Prevent downgrade attacks with HTTP strict transport security. Add HSTS "headers"
to static.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 when CORS 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.
The heroku/static
buildpack (see: π Architecture) provides Proxy Backends configuration to utilize Nginx for high-performance proxies in production.
Add "proxies"
to static.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-in proxy for development. This may be configured to match the behavior of proxy for deployment.
Add "proxy"
to package.json
:
{
"proxy": {
"/api": {
"target": "http://localhost:8000",
"pathRewrite": {
"^/api": "/"
}
}
}
}
Replace http://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.com
REACT_APP_CLIENT_ID=XyzxYzxyZ
Two versions of variables are supported. In addition to compile-time variables applied during build the app supports variables set at runtime, applied as each web dyno starts-up.
Requirement | Compile-time | Runtime |
---|---|---|
never changes for a build | β | |
support for continuous delivery | β | |
updates immediately when setting new config vars | β | |
different values for staging & production (in a pipeline) | β | |
ex: REACT_APP_BUILD_VERSION (static fact about the bundle) |
β | |
ex: REACT_APP_DEBUG_ASSERTIONS (prune code from bundle) |
β | |
ex: REACT_APP_API_URL (transient, external reference) |
β | |
ex: REACT_APP_FILEPICKER_API_KEY (Add-on config vars) |
β |
β»οΈ 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 the runtime env npm package:
npm install @mars/heroku-js-runtime-env --save
Then, require/import it to use the vars within components:
import React, { Component } from 'react';
import runtimeEnv from '@mars/heroku-js-runtime-env';
class App extends Component {
render() {
// Load the env object.
const env = runtimeEnv();
// β¦then use values just like `process.env`
return (
<code>Runtime env var example: { env.REACT_APP_HELLO }</code>
);
}
}
\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 with REACT_APP_
.
-
create
.profile.d/000-react-app-exports.sh
-
make it executable
chmod +x .profile.d/000-react-app-exports.sh
-
add an
export
line for each variable:export REACT_APP_ADDON_CONFIG=${ADDON_CONFIG:-}
-
set-up & use Runtime configuration to access the variables
For example, to use the API key for the Filestack JS image uploader:
export REACT_APP_FILEPICKER_API_KEY=${FILEPICKER_API_KEY:-}
-
Confirm that your app is using this buildpack:
heroku buildpacks
If it's not using
create-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.
-
Check this README to see if it already mentions the issue.
-
Search our issues to see if someone else has experienced the same problem.
-
Search the internet for mentions of the error message and its subject module, e.g.
ENOENT "node-sass"
-
File a new issue. 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 master as 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
βοΈ Replace v1.2.1
with the desired release tag.
β»οΈ Then, commit & deploy to rebuild on the new buildpack version.
This buildpack combines several buildpacks, specified in .buildpacks
, to support zero-configuration deployment on Heroku:
heroku/nodejs
buildpack- installs complete
node
, puts it on the$PATH
- version specified in
package.json
,engines.node
node_modules/
cached between deployments
- installs complete
mars/create-react-app-inner-buildpack
- production build for create-react-app
- generates the default
static.json
- enables runtime environment variables
heroku/static
buildpack- Nginx web server
- launches via
bin/boot
- configure via
static.json
; see options specific to this buildpack and all 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 a Procfile.
Some kind feedback pointed out that this buildpack is not necessarily specific to create-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 file
build/index.html
or the root specified instatic.json
exists at runtime.