runtime-env-cra-fallback
v0.2.6
Published
A runtime environment handler for create-react-apps with fallbacks
Downloads
248
Maintainers
Readme
Runtime-env-cra-fallback
runtime-env-cra-fallback
allows falling back to .env
values in case environment key cannot be found in process.env
A runtime environment handler for React.js apps that have been bootstraped using create-react-app.
- Usage
- Requirements
- CLI Options
- Using in a Typescript app
- Usage in Docker
- Examples
- Test Coverage
- Contributors
Usage
The runtime-env-cra-fallback
package was meant to be used in Docker or VM based environments, where you have full control over how your application will start. Sadly, runtime-env-cra-fallback
can not be used if you are using S3 or another static file serving solution.
Supported node.js versions due to
yargs
is 12 or greaterInstallation
$ npm install runtime-env-cra-fallback
- Add the following to
public/index.html
inside the<head>
tag:
<!-- Runtime environment variables -->
<script src="%PUBLIC_URL%/runtime-env.js"></script>
- Modify your
start
script to the following in yourpackage.json
:
...
"scripts": {
"start": "NODE_ENV=development runtime-env-cra-fallback --config-name=./public/runtime-env.js && react-scripts start",
...
}
...
- If you are on windows, you need to use cross-env
"scripts": {
"start": "cross-env NODE_ENV=development runtime-env-cra-fallback --config-name=./public/runtime-env.js && react-scripts start",
...
}
The script parses everything based on your .env
file and adds it to window.__RUNTIME_CONFIG__
.
If you pass NODE_ENV=development
for the script, it will use the values from your .env
, but if you provide anything else than development
or nothing for NODE_ENV
it will parse environment variables from process.env
. This way you can dynamically set your environment variables in production/staging environments without the need to rebuild your project.
Requirements
This script uses your .env
file by default to parse the environment variables to window.__RUNTIME_CONFIG__
, so be sure to have one in your project! After modifying the start
script and public/index.html
described in the section above, you should be good to go!
CLI options
- Display the help section.
$ runtime-env-cra-fallback --help | -h
- Relative path and file name that will be generated. Default is
./runtime-env.js
$ runtime-env-cra-fallback --config-name | -cn
- Relative path and name of your
env
file. Default is./.env
$ runtime-env-cra-fallback --env-file | -ef
Typescript usage
- Create
./src/types/globals.ts
file and pase the following (modify the__RUNTIME_CONFIG__
properties to match your environment):
export {};
declare global {
interface Window {
__RUNTIME_CONFIG__: {
API_URL: string;
NODE_ENV: string;
};
}
}
- Add
"include": ["src/types"]
to yourtsconfig.json
.
{
"compilerOptions": { ... },
"include": ["src/types"]
}
Usage in Docker
You must have an example of your env
layout. A project usually have a .env.example
which represents that and will not contain any sensitive information.
Inside a docker container we can lean on the .env.example
. Make sure your .env.example
is always up to date!
- Using in an alpine based container
# copy .env.example as .env to the container
COPY .env.example .env
# install nodejs & npm
RUN apk add --update nodejs
RUN apk add --update npm
# install runtime-env-cra package
RUN npm i -g runtime-env-cra
# start the app with the following CMD
CMD ["/bin/sh", "-c", "runtime-env-cra-fallback && nginx -g \"daemon off;\""]
Examples
- Create react app with typescript template, including Dockerfile and docker-compose. (source)
- Create react app without typescript, including Dockerfile and docker-compose. (source)
Test coverage
-------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
generateConfig.js | 100 | 100 | 100 | 100 |
utils.js | 100 | 100 | 100 | 100 |
-------------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests: 5 passed, 5 total
Snapshots: 0 total
Time: 1.751 s
Contributors
If you find a bug or have a question about the usage, feel free to open an issue!