Remix does not do anything directly with environment variables (except during local development), but there are some patterns we find useful that we'll share in this guide.
Environment Variables are values that live on the server that your application can use. You may be familiar with the ubiquitous NODE_ENV
. Your deployment server probably automatically sets that to "production".
remix build
compiles using the value of process.env.NODE_ENV
if it corresponds with a valid mode: "production", "development" or "test". If the value of process.env.NODE_ENV
is invalid, "production" is used as a default.
Here are some example environment variables you might find in the wild:
DATABASE_URL
: The URL for a Postgres DatabaseSTRIPE_PRIVATE_KEY
: The key a checkout workflow will use on the serverSTRIPE_PUBLIC_KEY
: The key a checkout workflow will use on the browserIf your experience with web development is primarily with the JS frameworks in the last few years, you might think of these as something for your build to use. While they can be useful for bundling code, traditionally those are "build arguments" not environment variables. Environment variables are most useful at runtime on the server. For example, you can change an environment variable to change the behavior of your app without rebuilding or even redeploying.
If you're using the remix dev
server to run your project locally, it has built-in support for dotenv.
First, create an .env
file in the root of your project:
touch .env
.env
file to git, the point is that it contains secrets!
Edit your .env
file.
SOME_SECRET=super-secret
Then, when running remix dev
you will be able to access those values in your loaders/actions:
export async function loader() {
console.log(process.env.SOME_SECRET);
}
If you're using the @remix-run/cloudflare-pages
adapter, env variables work a little differently. Since Cloudflare Pages are powered by Functions, you'll need to define your local environment variables in the .dev.vars
file. It has the same syntax as .env
example file mentioned above.
Then, you can pass those through via getLoadContext
in your server file:
export const onRequest = createPagesFunctionHandler({
build,
getLoadContext(context) {
// Hand-off Cloudflare ENV vars to the Remix `context` object
return { env: context.env };
},
mode: process.env.NODE_ENV,
});
And they'll be available via Remix's context
in your loader
/action
functions:
export const loader = async ({ context }: LoaderArgs) => {
console.log(context.env.SOME_SECRET);
};
Note that .env
files are only for development. You should not use them in production, so Remix doesn't load them when running remix serve
. You'll need to follow your host's guides on adding secrets to your production server, via the links below.
Environment variables when deployed to production will be handled by your host, for example:
Some folks ask if Remix can let them put environment variables into browser bundles. It's a common strategy in build-heavy frameworks. However, this approach is a problem for a few reasons:
Instead we recommend keeping all of your environment variables on the server (all the server secrets as well as the stuff your JavaScript in the browser needs) and exposing them to your browser code through window.ENV
. Since you always have a server, you don't need this information in your bundle, your server can provide the client-side environment variables in the loaders.
Return ENV
for the client from the root loader - Inside your loader you can access your server's environment variables. Loaders only run on the server and are never bundled into your client-side JavaScript.
export async function loader() {
return json({
ENV: {
STRIPE_PUBLIC_KEY: process.env.STRIPE_PUBLIC_KEY,
FAUNA_DB_URL: process.env.FAUNA_DB_URL,
},
});
}
export function Root() {
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<Scripts />
</body>
</html>
);
}
Put ENV
on window - This is how we hand off the values from the server to the client. Make sure to put this before <Scripts/>
export async function loader() {
return json({
ENV: {
STRIPE_PUBLIC_KEY: process.env.STRIPE_PUBLIC_KEY,
},
});
}
export function Root() {
const data = useLoaderData<typeof loader>();
return (
<html lang="en">
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<script
dangerouslySetInnerHTML={{
__html: `window.ENV = ${JSON.stringify(
data.ENV
)}`,
}}
/>
<Scripts />
</body>
</html>
);
}
Access the values
import { loadStripe } from "@stripe/stripe-js";
export async function redirectToStripeCheckout(
sessionId
) {
const stripe = await loadStripe(
window.ENV.STRIPE_PUBLIC_KEY
);
return stripe.redirectToCheckout({ sessionId });
}