npm package: @patrickaigbogunoti/x-env
Description: Typed .env manager for modern TypeScript projects (Vite, Next.js, etc.)
Author: Patrick Aigbogun Oti
Latest version: 0.2.139

# X-Env

🚀 **Modern, type-safe environment variable management for TypeScript projects**

X-Env eliminates the guesswork and runtime errors of working with environment variables by providing full TypeScript support, autocompletion, and compile-time safety for your `.env` files.

## 🎯 Problems X-Env Solves

### ❌ Before X-Env
```typescript
// No type safety - typos cause runtime errors
const apiUrl = process.env.NEXT_PUBLC_API_URL; // Typo!
const secret = process.env.SECRET_KEY; // Might be undefined

// No autocompletion - you have to remember variable names
const dbUrl = process.env.DATABASE_URL;

// Client/server confusion - accidentally exposing secrets
if (typeof window !== 'undefined') {
  // This could expose private keys!
  const privateKey = process.env.PRIVATE_KEY;
}
```

### ✅ After X-Env
```typescript
import { getClientEnv, getServerEnv } from './lib/env-helpers';

// Full type safety and autocompletion
const apiUrl = getClientEnv('NEXT_PUBLIC_API_URL'); // ✅ Autocomplete works!
const secret = getServerEnv('SECRET_KEY'); // ✅ Server-only, type-safe

// Compile-time errors for typos
const badUrl = getClientEnv('NEXT_PUBLC_API_URL'); // ❌ TypeScript error!

// Runtime protection
const privateKey = getServerEnv('PRIVATE_KEY'); // ❌ Throws on client
```

## 🌟 Key Features

- **🎯 Type Safety**: Full TypeScript support with autocompletion for all your env variables
- **🔒 Client/Server Safety**: Prevents accidentally exposing server secrets to the browser
- **⚡ Zero Config**: Works out of the box with sensible defaults
- **🔄 Auto-Generated Types**: Scans your `.env` files and generates TypeScript definitions
- **🚀 Framework Agnostic**: Works with Next.js, Vite, Remix, and more
- **📝 IntelliSense**: Get autocomplete suggestions for all your environment variables

## 📦 Installation

```bash
npm install @patrickaigbogunoti/x-env
# or
pnpm add @patrickaigbogunoti/x-env
# or
yarn add @patrickaigbogunoti/x-env
```

## 🚀 Quick Start

### 1. Initialize X-Env in your project

```bash
npx x-env init
```

This creates:
- `config/env/index.ts` - Your configuration file
- `lib/env-helpers.ts` - Type-safe helper functions
- Updates your `tsconfig.json` with proper paths

### 2. Configure your environment files

```typescript
// config/env/index.ts
import { defineConfig } from '@patrickaigbogunoti/x-env';

export default defineConfig({
  envFiles: ['.env', '.env.local', '.env.production'],
  publicPrefix: ['NEXT_PUBLIC_', 'VITE_'], // Support multiple prefixes
  generated: 'x-env.d.ts',
  entryPoints: ['next.config.ts', 'vite.config.ts'] // Multiple entry points
});
```

### 3. Set up your `.env` file

```bash
# .env
DATABASE_URL=postgresql://localhost:5432/mydb
SECRET_KEY=super-secret-key
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_APP_NAME=My App
```

### 4. Generate types from your environment variables

```bash
npx x-env generate
```

This scans your `.env` files, creates TypeScript definitions for all your variables, and automatically injects the `Load()` function into your configured entry points.

### 5. Use type-safe environment variables

```typescript
// lib/algolia.ts (server-side)
import { getServerEnv, getClientEnv } from './lib/env-helpers';

// Server-only variables (private)
const adminKey = getServerEnv('ALGOLIA_ADMIN_KEY'); // ✅ Type-safe
const dbUrl = getServerEnv('DATABASE_URL');

// Client-safe variables (public)
const appId = getClientEnv('NEXT_PUBLIC_ALGOLIA_APP_ID');
const searchKey = getClientEnv('NEXT_PUBLIC_ALGOLIA_SEARCH_KEY');
```

### 6. Load environment variables in your config

The `generate` command automatically injects the `Load()` function into your configured entry points. If you need to add it manually:

```typescript
// next.config.js (already injected by generate command)
import { Load } from '@patrickaigbogunoti/x-env/server';

Load(); // Loads your .env files into process.env

/** @type {import('next').NextConfig} */
const nextConfig = {
  // your config
};

export default nextConfig;
```

## 💡 Usage Examples

### Next.js App Router

```typescript
// app/components/search.tsx
'use client';

import { getClientEnv } from '@/lib/env-helpers';

export function SearchComponent() {
  // ✅ Type-safe, autocomplete works
  const apiUrl = getClientEnv('NEXT_PUBLIC_API_URL');
  
  // ❌ This would throw at runtime (server-only variable)
  // const secret = getServerEnv('SECRET_KEY');
  
  return <div>Search powered by {apiUrl}</div>;
}
```

```typescript
// app/api/users/route.ts
import { getServerEnv } from '@/lib/env-helpers';

export async function GET() {
  // ✅ Server-only, secure
  const dbUrl = getServerEnv('DATABASE_URL');
  const secretKey = getServerEnv('SECRET_KEY');
  
  // Connect to database using dbUrl...
  return Response.json({ users: [] });
}
```

### Vite + React

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { Load } from '@patrickaigbogunoti/x-env/server';

Load(); // Load environment variables

export default defineConfig({
  // your vite config
});
```

```typescript
// src/api/client.ts
import { getClientEnv } from './lib/env-helpers';

const apiClient = axios.create({
  baseURL: getClientEnv('VITE_API_URL'), // ✅ Type-safe
  timeout: 5000
});
```

## 🛠️ Available Commands

- `npx x-env init` - Initialize X-Env in your project
- `npx x-env generate` - Generate TypeScript definitions from your .env files and inject Load() into entry points
- `npx x-env watch` - Watch for changes and auto-regenerate types

## 🎛️ Configuration Options

```typescript
// config/env/index.ts
export default defineConfig({
  // Environment files to load (in order)
  envFiles: ['.env', '.env.local', '.env.production'],
  
  // Prefixes for public environment variables (supports multiple)
  publicPrefix: ['NEXT_PUBLIC_', 'VITE_', 'PUBLIC_'],
  
  // Output file for generated types
  generated: 'x-env.d.ts',
  
  // Entry points where Load() should be auto-injected
  entryPoints: ['next.config.ts', 'vite.config.ts', 'app.ts']
});
```

## 🔐 Security Features

X-Env helps prevent common security mistakes:

1. **Server-only protection**: `getServerEnv()` throws an error if called in browser code
2. **Public/private separation**: Only variables with your `publicPrefix` are accessible via `getClientEnv()`
3. **Compile-time checks**: TypeScript catches typos and undefined variables before runtime

## 📚 Framework Support

X-Env works with any TypeScript project, with built-in support for:

- ✅ **Next.js** (App Router & Pages Router)
- ✅ **Vite** (React, Vue, Svelte)
- ✅ **Remix**
- ✅ **Nuxt** (coming soon)
- ✅ **SvelteKit** (coming soon)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.