Day22 - Astro Series: Environment Variables

Introduction

This chapter introduces environment variables in Astro and how you can use them.

Why use environment variables?

In the real world you often face multiple development environments, such as development and production, and each stage may use its own API server. Instead of hardcoding server addresses in your code, you can create “project-scoped variables” via environment variables to let the same code adapt to different environments. Environment variables also allow developers to store sensitive information (like API keys or database passwords) in a secure place instead of hardcoding them. In summary, the benefits of using environment variables include:

1. Security
2. Maintainability
3. Configurability

Accessing environment variables

Variables are exposed on the import.meta.env object. Below are some default environment variables and their explanations:

• import.meta.env.MODE: The mode the site is running in. It is development when running astro dev, and production when running astro build.
• import.meta.env.PROD: true when in production mode, otherwise false.
• import.meta.env.DEV: true when in development mode, otherwise false.
• import.meta.env.BASE_URL: The base URL of the site, determined by the [base property](https://docs.astro.build/en/reference/configuration-reference/#base🔗) in the config.
• import.meta.env.SITE: The deployed site URL, determined by the [site property](https://docs.astro.build/en/reference/configuration-reference/#site🔗) in the config.
• import.meta.env.ASSETS_PREFIX: The prefix for asset links generated by Astro, if the build.assetsPrefix property🔗 is set in the config.

Environment variables can also be used to detect the current project mode and take actions accordingly, such as showing draft posts during development but hiding them in production.

const publishedPosts = await getCollection('post', (post) => (import.meta.env.PROD ? !post.data.isDraft : true));

Using environment variables

Astro uses Vite’s built-in environment variable support, so the way to use them is identical. You can use any of Vite’s methods🔗 to manage them.

Create a .env file

# 只在伺服器上運行有效
PUBLIC_IMAGEAPI=https://picsum.photos
# 任何地方都有效
SECRET_PASSWORD=password123

In the example above, environment variables prefixed with PUBLIC_ are available throughout the project on both server and client, while variables without that prefix (like SECRET_) are only available on the server.

// 使用環境變數
fetch(`${import.meta.env.PUBLIC_IMAGEAPI}/300/300`);

Create environment-specific .env files

You can append a mode name (like production or development) to the filename, e.g. .env.production or .env.development, so that the variables in that file only take effect for the corresponding mode.

Add environment variables via the CLI

Environment variables can also be added at runtime via the CLI, but note that variables set this way will be available across the whole project, including the client:

IMAGEAPI=https://picsum.photos npm run dev

Further reading

• Using environment variables🔗 - Astro
• Day22 - 環境變數🔗 - Same article also published on the iThome Ironman competition site