wasp/web/docs/project/env-vars.md

title
Env Variables

Environment variables are used to configure projects based on the context in which they run. This allows them to exhibit different behaviors in different environments, such as development, staging, or production.

For instance, during development, you may want your project to connect to a local development database running on your machine, but in production, you may prefer it to connect to the production database. Similarly, in development, you may want to use a test Stripe account, while in production, your app should use a real Stripe account.

While some env vars are required by Wasp, such as the database connection or secrets for social auth, you can also define your env vars for any other useful purposes, and then access them in the code.

In Wasp, you can use environment variables in both the client and the server code.

Client Env Vars

Client environment variables are embedded into the client code during the build and shipping process, making them public and readable by anyone. Therefore, you should never store secrets in them (such as secret API keys -> you can provide those to server instead).

To enable Wasp to pick them up, client env vars must be prefixed with REACT_APP_, for example: REACT_APP_SOME_VAR_NAME=....

You can read them from the client code like this:

console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)

console.log(import.meta.env.REACT_APP_SOME_VAR_NAME)

Check below on how to define them.

Server Env Vars

In server environment variables, you can store secret values (e.g. secret API keys) since they are not publicly readable. You can define them without any special prefix, such as SOME_VAR_NAME=....

You can read the env vars from server code like this:

console.log(process.env.SOME_VAR_NAME)

console.log(process.env.SOME_VAR_NAME)

Check below on how to define them.

Defining Env Vars in Development

During development (wasp start), there are two ways to provide env vars to your Wasp project:

1. Using .env files. (recommended)
2. Using shell. (useful for overrides)

1. Using .env (dotenv) Files

This is the recommended method for providing env vars to your Wasp project during development.

In the root of your Wasp project you can create two distinct files:

• .env.server for env vars that will be provided to the server.

Variables are defined in these files in the form of NAME=VALUE, for example:

DATABASE_URL=postgresql://localhost:5432
SOME_VAR_NAME=somevalue

• .env.client for env vars that will be provided to the client.

  Variables are defined in these files in the form of NAME=VALUE, for example:

  REACT_APP_SOME_VAR_NAME=somevalue
  

.env.server should not be committed to version control as it can contain secrets, while .env.client can be versioned as it must not contain any secrets. By default, in the .gitignore file that comes with a new Wasp app, we ignore all dotenv files.

:::info Dotenv files dotenv files are a popular method for storing configuration: to learn more about them in general, check out the dotenv npm package. :::

2. Using Shell

If you set environment variables in the shell where you run your Wasp commands (e.g., wasp start), Wasp will recognize them.

You can set environment variables in the .profile or a similar file, which will set them permanently, or you can set them temporarily by defining them at the start of a command (SOME_VAR_NAME=SOMEVALUE wasp start).

This is not specific to Wasp and is simply how environment variables can be set in the shell.

Defining environment variables in this way can be cumbersome even for a single project and even more challenging to manage if you have multiple Wasp projects. Therefore, we do not recommend this as a default method for providing environment variables to Wasp projects during development, you should use .env files instead. However, it can be useful for occasionally overriding specific environment variables because environment variables set this way take precedence over those defined in .env files.

Defining Env Vars in Production

While in development, we had the option of using .env.client and .env.server files which made it easy to define and manage env vars. However, for production, .env.client and .env.server files will be ignored, and we need to provide env vars differently.

Client Env Vars

Client env vars are embedded into the client code during the build process, making them public and readable by anyone. Therefore, you should never store secrets in them (such as secret API keys).

When building for production .env.client will be ignored, since it is meant to be used only during development. Instead, you should provide the production client env vars directly to the build command that turns client code into static files:

REACT_APP_SOME_VAR_NAME=somevalue REACT_APP_SOME_OTHER_VAR_NAME=someothervalue npm run build

Check the deployment docs for more details.

Also, notice that you can't and shouldn't provide env vars to the client code by setting them on the hosting provider where you deployed them (unlike server env vars, where this is how you should do it). Your client code will ignore those, as at that point client code is just static files.

:::info How it works What happens behind the scenes is that Wasp will replace all occurrences of import.meta.env.REACT_APP_SOME_VAR_NAME in your client code with the env var value you provided. This is done during the build process, so the value is embedded into the static files produced from the client code.

Read more about it in Vite's docs. :::

Server Env Vars

When building for production .env.server will be ignored, since it is meant to be used only during development.

You can provide production env vars to your server code in production by defining them and making them available on the server where your server code is running.

Setting this up will highly depend on where you are deploying your Wasp project, but in general it comes down to defining the env vars via mechanisms that your hosting provider provides.

For example, if you deploy your project to Fly, you can define them using the flyctl CLI tool:

flyctl secrets set SOME_VAR_NAME=somevalue

You can read a lot more details in the deployment section of the docs. We go into detail on how to define env vars for each deployment option.