API: {import.meta.env.VITE_API_URL}
App: {import.meta.env.VITE_APP_NAME}
);
}
```
**Key points:**
- Must use `VITE_` prefix
- Injected at build time
- Available in client code
- Access via `import.meta.env.VITE_*`
### Type Safety
Create `env.d.ts` for TypeScript autocomplete:
```typescript
interface ImportMetaEnv {
readonly VITE_API_URL: string;
readonly VITE_APP_NAME: string;
readonly VITE_USER_ID: string;
}
interface ImportMeta {
readonly env: ImportMetaEnv;
}
```
Now TypeScript will autocomplete and type-check your environment variables.
## Private Environment Variables
Private variables are server-only and should NOT use the `VITE_` prefix. Access them via `process.env` in server code.
### Basic Setup
```env
DB_HOST=somedb://192.110.0
DB_PASSWORD=super_secret_password_hash
API_SECRET_KEY=secret123
```
Access in server code:
```tsx
"use server";
export async function getData() {
const client = new DB({
host: process.env.DB_HOST,
password: process.env.DB_PASSWORD,
});
// Use private variables
const apiKey = process.env.API_SECRET_KEY;
return client.query();
}
```
**Key points:**
- NO `VITE_` prefix
- Only accessible in server code
- Use `process.env` to access
- Not exposed to client
### Type Safety for Server Variables
Add to `env.d.ts`:
```typescript
declare namespace NodeJS {
interface ProcessEnv {
readonly DB_HOST: string;
readonly DB_PASSWORD: string;
readonly API_SECRET_KEY: string;
}
}
```
## Environment Files
### Development (.env)
```env
VITE_API_URL=http://localhost:3000
DB_HOST=localhost
DB_PASSWORD=dev_password
```
### Production (.env.production)
```env
VITE_API_URL=https://api.production.com
DB_HOST=prod-db.example.com
DB_PASSWORD=prod_secret_password
```
### Local Override (.env.local)
```env
# Overrides .env, not committed to git
VITE_API_URL=http://localhost:4000
```
**File priority (highest to lowest):**
1. `.env.local` (always loaded, ignored by git)
2. `.env.[mode].local` (e.g., `.env.production.local`)
3. `.env.[mode]` (e.g., `.env.production`)
4. `.env`
## Security Best Practices
### ❌ Never Expose Secrets
```env
# ❌ WRONG - This will be exposed to client!
VITE_DB_PASSWORD=secret123
# ✅ CORRECT - No VITE_ prefix
DB_PASSWORD=secret123
```
### ✅ Verify Client Exposure
```tsx
// Check what's exposed
console.log(import.meta.env.VITE_SECRET_KEY); // ✅ Exposed (if prefixed)
console.log(import.meta.env.DB_PASSWORD); // ✅ undefined (safe)
```
### ✅ Use Server Actions for Secrets
```tsx
// ❌ WRONG - Exposes API key to client
function ClientComponent() {
const apiKey = import.meta.env.VITE_API_KEY; // Exposed!
fetch(`/api?key=${apiKey}`);
}
// ✅ CORRECT - Keep secret on server
"use server";
export async function fetchData() {
const apiKey = process.env.API_SECRET_KEY; // Server-only
return fetch(`/api?key=${apiKey}`);
}
```
## Runtime vs Build-Time
### Build-Time Variables (VITE_*)
```tsx
// Replaced at build time
const apiUrl = import.meta.env.VITE_API_URL;
// After build: const apiUrl = "https://api.example.com";
```
**Characteristics:**
- Replaced during build
- Different values per build
- Cannot change at runtime
- Bundled into client code
### Runtime Variables (Server)
```tsx
// Accessed at runtime
const dbHost = process.env.DB_HOST;
// Value from environment at runtime
```
**Characteristics:**
- Accessed at runtime
- Can change without rebuild
- Server-only access
- Not bundled
## Common Patterns
### API Configuration
```env
# .env
VITE_API_URL=http://localhost:3000
VITE_API_TIMEOUT=5000
```
```tsx
// Client code
const apiUrl = import.meta.env.VITE_API_URL;
const timeout = Number(import.meta.env.VITE_API_TIMEOUT) || 5000;
fetch(`${apiUrl}/data`, { signal: AbortSignal.timeout(timeout) });
```
### Database Configuration
```env
# .env (server-only)
DATABASE_URL=postgresql://user:pass@localhost:5432/db
REDIS_URL=redis://localhost:6379
```
```tsx
// Server code
"use server";
export async function connectDB() {
const db = new Database(process.env.DATABASE_URL);
const redis = new Redis(process.env.REDIS_URL);
return { db, redis };
}
```
### Feature Flags
```env
# .env
VITE_ENABLE_ANALYTICS=true
VITE_ENABLE_DEBUG=false
```
```tsx
// Client code
const enableAnalytics = import.meta.env.VITE_ENABLE_ANALYTICS === "true";
const enableDebug = import.meta.env.VITE_ENABLE_DEBUG === "true";
if (enableAnalytics) {
initAnalytics();
}
if (enableDebug) {
console.log("Debug mode enabled");
}
```
### Environment-Specific Config
```tsx
// config.ts
export const config = {
apiUrl: import.meta.env.VITE_API_URL || "http://localhost:3000",
isDev: import.meta.env.DEV,
isProd: import.meta.env.PROD,
mode: import.meta.env.MODE,
};
```
## TypeScript Setup
Complete `env.d.ts` example:
```typescript
///