Environment Variables

Relevant source files

The following files were used as context for generating this wiki page:

• src/shared/config/env.ts
• vite.config.ts
• package.json
• netlify.toml
• index.html
• src/app/App.tsx

This project utilizes Vite to manage environment variables, coupled with Zod for robust, type-safe validation. This system ensures that the application receives the correct configuration for different environments (development, production) and prevents it from running with invalid or missing settings. Variables are exposed to the client-side code through import.meta.env, with a clear distinction between public variables (prefixed with VITE_) and Vite's built-in variables.

The core of this system resides in src/shared/config/env.ts, which defines a schema, performs validation at startup, and exports a clean, typed env object for use throughout the application. This approach centralizes configuration management and enhances application stability.

Schema Definition and Validation

At the heart of the environment variable system is a Zod schema that defines the expected shape and type of all variables. This ensures that any value accessed from the environment is parsed, typed, and validated before the application fully initializes.

Sources: src/shared/config/env.ts

Validation Flow

The application validates environment variables at startup. The process involves reading from import.meta.env, parsing the values against the predefined Zod schema, and either exporting the validated data or throwing a critical error if validation fails.

The diagram below illustrates the validation process.

Zod Schema

The envSchema object defines the contract for the application's environment variables. It specifies each variable's type and whether it is optional or has a default value.

// src/shared/config/env.ts:3-10
const envSchema = z.object({
  VITE_APP_TITLE: z.string().optional(),
  BASE_URL: z.string().default("/"),
  DEV: z.boolean(),
  PROD: z.boolean(),
  SSR: z.boolean(),
});

Sources: src/shared/config/env.ts:3-10

If the safeParse method fails, a formatted error message is logged to the console, and an Error is thrown, which stops the application from proceeding with an invalid configuration.

// src/shared/config/env.ts:19-22
if (!_env.success) {
  console.error("❌ Invalid environment variables:", _env.error.format());
  throw new Error("Invalid environment variables");
}

Sources: src/shared/config/env.ts:19-22

Available Variables

The application consumes both custom environment variables and built-in variables provided by Vite. Custom variables intended for client-side exposure must be prefixed with VITE_.

Variable	Zod Type	Default Value	Description	Source File
VITE_APP_TITLE	z.string()	(none)	An optional string for the application title.	src/shared/config/env.ts:4
BASE_URL	z.string()	/	The base public path when the app is served. Provided by Vite.	src/shared/config/env.ts:5
DEV	z.boolean()	(none)	true when the app is running in development mode. Provided by Vite.	src/shared/config/env.ts:6
PROD	z.boolean()	(none)	true when the app is running in production mode. Provided by Vite.	src/shared/config/env.ts:7
SSR	z.boolean()	(none)	true when the app is running in a server-side rendering context.	src/shared/config/env.ts:8

Sources: src/shared/config/env.ts:3-10, vite.config.ts

Build and Deployment

The environment variable system is integrated into the project's build and deployment pipeline.

Build Scripts

The package.json file defines scripts that use Vite to build and serve the application. Vite automatically loads the appropriate .env files based on the mode (development or production) it is run in.

// package.json:6-12
"scripts": {
  "dev": "vite",
  "dev:host": "vite --host",
  "build": "vite build",
  "lint": "eslint .",
  "preview": "vite preview",
  "optimize-images": "node scripts/optimize-images.js"
},

Sources: package.json:6-12

Netlify Deployment

The project is configured for deployment on Netlify. The netlify.toml file specifies the build command, which in turn uses Vite. Environment variables can be set in the Netlify UI, and they will be available to the npm run build command during the deployment process.

# netlify.toml:1-3
[build]
  command = "npm run build"
  publish = "dist"

This configuration ensures that the same build process that handles environment variables locally is used in the production deployment environment.

Sources: netlify.toml:1-3