diff --git a/src/pages/en/guides/configuring-astro.md b/src/pages/en/guides/configuring-astro.md index d12c2ed6f0fc0..ca77e724c3ea6 100644 --- a/src/pages/en/guides/configuring-astro.md +++ b/src/pages/en/guides/configuring-astro.md @@ -140,6 +140,11 @@ export default defineConfig({ This can be helpful if you have scripts with names that might be impacted by ad blockers (e.g. `ads.js` or `google-tag-manager.js`). +## Environment Variables +Astro evaluates configuration files before it loads your other files. As such, you can't use `import.meta.env` or access environment variables that were set in `.env` files. + +You can use `process.env` in a configuration file to access other environment variables, like those [set by the CLI](/en/guides/environment-variables/#using-the-cli). + ## Configuration Reference 📚 Read Astro's [API configuration reference](/en/reference/configuration-reference/) for a full overview of all supported configuration options. diff --git a/src/pages/en/guides/environment-variables.md b/src/pages/en/guides/environment-variables.md index 0ce74606cc854..536c9c13b0c39 100644 --- a/src/pages/en/guides/environment-variables.md +++ b/src/pages/en/guides/environment-variables.md @@ -2,10 +2,10 @@ layout: ~/layouts/MainLayout.astro title: Using environment variables description: Learn how to use environment variables in an Astro project. +setup: import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro' i18nReady: true --- - -Astro uses Vite for environment variables, and allows you to [use any of its methods](https://vitejs.dev/guide/env-and-mode.html) to get and set environment variables. +Astro uses Vite's built-in support for environment variables, and lets you [use any of its methods](https://vitejs.dev/guide/env-and-mode.html) to work with them. Note that while _all_ environment variables are available in server-side code, only environment variables prefixed with `PUBLIC_` are available in client-side code for security purposes. @@ -16,18 +16,23 @@ PUBLIC_ANYBODY=there In this example, `PUBLIC_ANYBODY` (accessible via `import.meta.env.PUBLIC_ANYBODY`) will be available in server or client code, while `SECRET_PASSWORD` (accessible via `import.meta.env.SECRET_PASSWORD`) will be server-side only. -## Default environment Variables +:::caution +`import.meta.env` and `.env` files are not available inside [configuration files](/en/guides/configuring-astro/#environment-variables). +::: + +## Default environment variables Astro includes a few environment variables out-of-the-box: -- `import.meta.env.MODE` (`development` | `production`): the mode your site is running in. This is `development` when running `astro dev` and `production` when running `astro build`. -- `import.meta.env.BASE_URL` (`string`): the base url your site is being served from. This is determined by the [`base` config option](/en/reference/configuration-reference/#base). -- `import.meta.env.PROD` (`boolean`): whether your site is running in production. -- `import.meta.env.DEV` (`boolean`): whether your site is running in development (always the opposite of `import.meta.env.PROD`). -- `import.meta.env.SITE` (`string`): [The `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`. +- `import.meta.env.MODE`: The mode your site is running in. This is `development` when running `astro dev` and `production` when running `astro build`. +- `import.meta.env.PROD`: `true` if your site is running in production; `false` otherwise. +- `import.meta.env.DEV`: `true` if your site is running in development; `false` otherwise. Always the opposite of `import.meta.env.PROD`. +- `import.meta.env.BASE_URL`: The base url your site is being served from. This is determined by the [`base` config option](/en/reference/configuration-reference/#base). +- `import.meta.env.SITE`: This is set to the [the `site` option](/en/reference/configuration-reference/#site) specified in your project's `astro.config`. ## Setting environment variables +### `.env` files Environment variables can be loaded from `.env` files in your project directory. You can also attach a mode (either `production` or `development`) to the filename, like `.env.production` or `.env.development`, which makes the environment variables only take effect in that mode. @@ -41,22 +46,36 @@ DB_PASSWORD="foobar" PUBLIC_POKEAPI="https://pokeapi.co/api/v2" ``` -```yaml -# Supported file names: -.env # loaded in all cases -.env.local # loaded in all cases, ignored by git -.env.[mode] # only loaded in specified mode -.env.[mode].local # only loaded in specified mode, ignored by git -``` +For more on `.env` files, [see the Vite documentation](https://vitejs.dev/guide/env-and-mode.html#env-files). + +### Using the CLI +You can also add environment variables as you run your project: + + + + ```shell + POKEAPI=https://pokeapi.co/api/v2 yarn run dev + ``` + + + ```shell + POKEAPI=https://pokeapi.co/api/v2 npm run dev + ``` + + + ```shell + POKEAPI=https://pokeapi.co/api/v2 pnpm run dev + ``` + + +:::caution +Variables set this way will be available everywhere within your project, including on the client. +::: ## Getting environment variables Instead of using `process.env`, with Vite you use `import.meta.env`, which uses the `import.meta` feature added in ES2020. -:::tip[Don't worry about browser support!] -Vite replaces all `import.meta.env` mentions with static values. -::: - For example, use `import.meta.env.PUBLIC_POKEAPI` to get the `PUBLIC_POKEAPI` environment variable. ```js /(?