bunjs-env/README.md

Cross-platform environment variable setter for Bun.js

# bunjs-env

Cross-platform environment variable setter optimized for Bun.js.

## Installation

```bash
# Install globally
bun install -g bunjs-env

# Or use with bunx (no installation required)
bunx bunjs-env NODE_ENV=production bun run start
```

## Usage

Set environment variables before running commands, works consistently across all platforms:

```bash
bunjs-env NODE_ENV=production bun run start
bunjs-env DEBUG=true API_KEY=secret bun run dev
bunjs-env NODE_ENV=test bun test
```

### Multiple Environment Variables
```bash
bunjs-env NODE_ENV=production PORT=3000 DEBUG=false bun run start
```

### Debug Mode
See exactly what environment variables are set and which command is executed:
```bash
bunjs-env --debug NODE_ENV=test bun run test
```

## Why bunjs-env?

Built specifically for the Bun ecosystem with native performance optimizations. Inspired by the excellent [cross-env](https://github.com/kentcdodds/cross-env) but optimized for Bun's unique capabilities:

- **Zero dependencies** - Lightweight and secure
- **Native Bun integration** - Uses Bun's built-in shell capabilities
- **TypeScript ready** - Works seamlessly with TypeScript projects
- **Fast execution** - Leverages Bun's performance advantages

*Note: If you're using Node.js, [cross-env](https://github.com/kentcdodds/cross-env) is the excellent standard choice. bunjs-env is designed specifically for Bun users who want native integration.*

## Examples

### Development
```bash
bunjs-env NODE_ENV=development DEBUG=true bun run dev
bunjs-env NODE_ENV=test DATABASE_URL=test.db bun test
```

### Production
```bash
bunjs-env NODE_ENV=production bun run build
bunjs-env NODE_ENV=production PORT=8080 bun run start
```

### CI/CD
```bash
bunjs-env NODE_ENV=test CI=true bun run test:coverage
```

## CLI Options

- `-h, --help` — Show help message
- `--debug` — Enable debug output showing environment variables and command execution

## Requirements

- Bun.js >= 1.0.0

## API

Environment variables must follow standard naming conventions:
- Start with a letter or underscore
- Contain only letters, numbers, and underscores
- Format: `KEY=value`

## Migration from cross-env

Switching from cross-env is straightforward - just replace `cross-env` with `bunjs-env`:

```bash
# Before (cross-env)
cross-env NODE_ENV=production npm run build

# After (bunjs-env)
bunjs-env NODE_ENV=production bun run build
```

## License

MIT License — see [LICENSE](LICENSE) for details.

## Related

- [cross-env](https://github.com/kentcdodds/cross-env)
- [Bun.js](https://bun.sh)