useEnvironment
A React Hook to load runtime environment variables from a JSON link.
Why?
See issue #578 for some background.
Usage
Install
npm install @ttoohey/react-use-environmentCreate an environment.json file in the public/ folder
# public/environment.json
{
"EXAMPLE_VAR": "Test value",
"ANOTHER": "Another value"
}Add a <link> tag to public/index.html
# public/index.html
<html>
<head>
...
<!--
environment.json provides runtime environment variables.
-->
<link
id="environment"
rel="preload"
as="script"
href="%PUBLIC_URL%/environment.json"
/>
...
</head>
<body>
...
</body>
</html>The environment can be loaded in any React component. For example, in
src/index.js load an API_URL to pass to an ApolloClient instance.
// src/index.js
import React, { Suspense } from "react";
import ApolloClient from "apollo-boost";
import { ApolloProvider } from "react-apollo-hooks";
import useEnvironment from "@gency/react-use-environment";
import App from "./App";
import Loading from "./Loading";
const Root = () => {
const { API_URL } = useEnvironment();
const client = new ApolloClient({ uri: API_URL });
return (
<ApolloProvider client={client}>
<App />
</ApolloProvider>
);
};
ReactDOM.render(
<React.Suspense fallback={<Loading />}>
<Root />
</React.Suspense>,
document.getElementById("root")
);A React Suspense component must be used as useEnvironment will
throw a promise while loading the JSON file.
API
The useEnvironment function accepts an options argument containing the
following entries:
-
linkId-- (default: "environment"). Use this to identify the id of the tag - suspense -- (default: true). Whether to use React Suspense for a fallback.
If suspense: false is used the return value contains three elements: [env, loading, error]
const [env, loading, error] = useEnvironment({ suspense: false });
if (loading) return "Loading...";
if (error) return "Error";
const { API_URL } = env;
// ... etcCreating environment.json
Development
If possible, structure development environments so that each developer can use the same configuration. This way the environment.json file can simply be committed to the Git repository.
If that's not possible, creating a public/environment.json file from the "start" script would normally be sufficient.
Staging and Production
As part of the build step have the public/environment.json file replaced with
a template file. This can be done in the build script in package.json
# src/environment.json
{
"API_URL": "$API_URL"
}# package.json
{
"scripts": {
"build": "react-scripts build && cp src/environment.json build/environment.json",
}
}When deploying the app replace the template file with one with the environment variables replaced.
For example, if creating a Docker image, something like the following can be used to do the environment variables substitution when the container starts.
# Dockerfile
FROM nginx:alpine
COPY build /usr/share/nginx/html
COPY build/environment.json /environment.json
RUN chown -R nginx:nginx /usr/share/nginx/html
CMD ["/bin/sh", "-c", "envsubst </environment.json >/usr/share/nginx/html/environment.json && nginx -g 'daemon off;'"]