66eaf2fc74
This PR removes the `/nx-api` pages from `nx-dev`. They are already redirected from `/nx-api` to either `/technologies` or `/reference/core-api` URLs. e.g. `/nx-api/nx` goes to `/reference/core-api/nx` and `/nx-api/react` goes to `/technologies/react/api` **Changes**: - Remove old `nx-api.json` from being generated in `scripts/documentation/generators/generate-manifests.ts` -- this was used to generate the sitemap - Remove `pages/nx-api` from Next.js app since we don't need them - Remove workaround from link checker `scripts/documentation/internal-link-checker.ts` -- the angular rspack/rsbuild and other workarounds are gone now that they are proper docs in `map.json` - Update Powerpack/Remote Cache reference docs to exclude API documents (since they are duplicated in the Intro page) -- `nx-dev/models-document/src/lib/mappings.ts` - All content in `docs` have been updated with new URL structure **Note:** Redirects are already handled, and Claude Code was used to verify the updated `docs/` URLs (see report below). The twelve 404s links were updated by hand. ## Verification Report https://gist.github.com/jaysoo/c7863fe7e091cb77929d1976165c357a
117 lines
4.9 KiB
Markdown
117 lines
4.9 KiB
Markdown
---
|
|
title: Define Environment Variables
|
|
description: Learn how to set and use environment variables in Nx projects, including file-based configuration, custom env files, and ad-hoc variable definition across different operating systems.
|
|
---
|
|
|
|
# Define Environment Variables
|
|
|
|
Environment variables are global system variables accessible by all the processes running under the Operating System (OS).
|
|
Environment variables are useful to store system-wide values such as the directories to search for executable programs
|
|
(PATH), OS version, Network Information, and custom variables. These env variables are passed at build time and used at
|
|
the runtime of an app.
|
|
|
|
## Set Environment Variables
|
|
|
|
By default, Nx will load any environment variables you place in the following files:
|
|
|
|
1. `apps/my-app/.env.[target-name].[target-configuration-name].local`
|
|
2. `apps/my-app/.env.[target-name].[target-configuration-name]`
|
|
3. `apps/my-app/.env.[target-name].local`
|
|
4. `apps/my-app/.env.[target-name]`
|
|
5. `apps/my-app/.[target-name].[target-configuration-name].local.env`
|
|
6. `apps/my-app/.[target-name].[target-configuration-name].env`
|
|
7. `apps/my-app/.[target-name].local.env`
|
|
8. `apps/my-app/.[target-name].env`
|
|
9. `apps/my-app/.env.local`
|
|
10. `apps/my-app/.local.env`
|
|
11. `apps/my-app/.env`
|
|
12. `.env.[target-name].[target-configuration-name].local`
|
|
13. `.env.[target-name].[target-configuration-name]`
|
|
14. `.env.[target-name].local`
|
|
15. `.env.[target-name]`
|
|
16. `.[target-name].[target-configuration-name].local.env`
|
|
17. `.[target-name].[target-configuration-name].env`
|
|
18. `.[target-name].local.env`
|
|
19. `.[target-name].env`
|
|
20. `.env.local`
|
|
21. `.local.env`
|
|
22. `.env`
|
|
|
|
{% callout type="warning" title="Order is important" %}
|
|
Nx will move through the above list, ignoring files it can't find, and loading environment variables
|
|
into the current process for the ones it can find. If it finds a variable that has already been loaded into the process,
|
|
it will ignore it. It does this for two reasons:
|
|
|
|
1. Developers can't accidentally overwrite important system level variables (like `NODE_ENV`)
|
|
2. Allows developers to create `.env.local` or `.local.env` files for their local environment and override any project
|
|
defaults set in `.env`
|
|
3. Allows developers to create target specific `.env.[target-name]` or `.[target-name].env` to overwrite environment variables for specific targets. For instance, you could increase the memory use for node processes only for build targets by setting `NODE_OPTIONS=--max-old-space-size=4096` in `.build.env`
|
|
|
|
For example:
|
|
|
|
1. `apps/my-app/.env.local` contains `NX_PUBLIC_API_URL=http://localhost:3333`
|
|
2. `apps/my-app/.env` contains `NX_PUBLIC_API_URL=https://api.example.com`
|
|
3. Nx will first load the variables from `apps/my-app/.env.local` into the process. When it tries to load the variables
|
|
from `apps/my-app/.env`, it will notice that `NX_PUBLIC_API_URL` already exists, so it will ignore it.
|
|
|
|
We recommend nesting your **app** specific `env` files in `apps/your-app`, and creating workspace/root level `env` files
|
|
for workspace-specific settings (like the [Nx Cloud token](/ci/recipes/security/access-tokens)).
|
|
{% /callout %}
|
|
|
|
### Environment Variables for Configurations
|
|
|
|
Nx will only load environment variable files for a particular configuration if that configuration is defined for a task, even if you specify that configuration name from the command line. So if there is no `development` configuration defined for the `app`'s `build` task, the following command will use `.env.build` instead of `.env.build.development`:
|
|
|
|
```shell
|
|
nx build app --configuration development
|
|
```
|
|
|
|
In order to have Nx actually use the `.env.build.development` environment variables, the `development` configuration needs to be set for the task (even if it is empty).
|
|
|
|
```jsonc {% fileName="apps/app/project.json" highlightLines=["5-7"] %}
|
|
{
|
|
"targets": {
|
|
"build": {
|
|
// ...
|
|
"configurations": {
|
|
"development": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Point to Custom Env Files
|
|
|
|
If you want to load variables from `env` files other than the ones listed above:
|
|
|
|
1. Use the [env-cmd](https://www.npmjs.com/package/env-cmd) package: `env-cmd -f .qa.env nx serve`
|
|
2. Use [dotenvx](https://github.com/dotenvx/dotenvx): `dotenvx run --env-file=.qa.env -- nx serve`
|
|
3. Use the `envFile` option of the [run-commands](/reference/core-api/nx/executors/run-commands#envfile) builder and execute your command inside of the builder
|
|
|
|
### Ad-hoc Variables
|
|
|
|
You can also define environment variables in an ad-hoc manner using support from your OS and shell.
|
|
|
|
**Unix systems**
|
|
|
|
In Unix systems, we need to set the environment variables before calling a command.
|
|
|
|
Let's say that we want to define an API URL for the application to use:
|
|
|
|
```shell
|
|
NX_PUBLIC_API_URL=http://localhost:3333 nx build myapp
|
|
```
|
|
|
|
**Windows (cmd.exe)**
|
|
|
|
```shell
|
|
set "NX_PUBLIC_API_URL=http://localhost:3333" && nx build myapp
|
|
```
|
|
|
|
**Windows (Powershell)**
|
|
|
|
```shell
|
|
($env:NX_PUBLIC_API_URL = "http://localhost:3333") -and (nx build myapp)
|
|
```
|