https://github.com/iamflowz/safe-ts-env
Helper function to parse environment variables from JSON files
https://github.com/iamflowz/safe-ts-env
awscdk cdk environment environment-variables npm npm-package react typescript typescript-library vue zod zod-validation
Last synced: about 2 months ago
JSON representation
Helper function to parse environment variables from JSON files
- Host: GitHub
- URL: https://github.com/iamflowz/safe-ts-env
- Owner: IamFlowZ
- License: other
- Created: 2025-05-17T13:14:57.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-19T22:33:02.000Z (about 1 year ago)
- Last Synced: 2025-10-21T07:53:04.524Z (8 months ago)
- Topics: awscdk, cdk, environment, environment-variables, npm, npm-package, react, typescript, typescript-library, vue, zod, zod-validation
- Language: HTML
- Homepage: https://www.npmjs.com/package/safe-ts-env
- Size: 11.7 MB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# safe-ts-env
A TypeScript library that provides type-safe environment configuration.
## Installation
```bash
npm install safe-ts-env
```
## Features
- **Type Safety**: Leverage TypeScript's type system to ensure your environment configurations are correctly typed
- **Runtime Validation**: Use Zod schemas to validate environment configurations at runtime
- **Flexible Path Handling**: Support for both string and array path formats
- **Error Handling**: Built-in error handling with optional debug logging
- **Zero Configuration**: Simple API that works out of the box
## Usage
### Basic Example
```typescript
import { getEnv } from 'safe-ts-env';
import { z } from 'zod';
// Define your environment schema using Zod
const envSchema = z.object({
name: z.string(),
region: z.string(),
stage: z.enum(['dev', 'staging', 'prod']),
instanceCount: z.number().int().positive(),
});
// Load and validate your environment configuration
const checkedEnv = getEnv('path/to/env/file.json', envSchema);
// TypeScript knows the exact shape of checkedEnv
console.log(checkedEnv.name); // string
console.log(checkedEnv.region); // string
console.log(checkedEnv.stage); // 'dev' | 'staging' | 'prod'
console.log(checkedEnv.instanceCount); // number
```
### Using Array Path
You can also provide the path as an array of path segments:
```typescript
const checkedEnv = getEnv(['path', 'to', 'env', 'file.json'], envSchema);
```
### Using with `process.env`
```typescript
const checkedEnv = getEnv('path/to/env/file.json', envSchema);
process.env = {
...process.env,
...Object.fromEntries(
Object.entries(checkedEnv).map(([key, value]) => [key, String(value)]),
),
};
```
### Using with CDK
```typescript
// Define your environment schema using Zod
const envSchema = z.object({
name: z.string(),
region: z.string(),
stage: z.enum(['dev', 'staging', 'prod']),
instanceCount: z.number().int().positive(),
});
const checkedEnv = getEnv('path/to/env/file.json', envSchema);
const stackProps = {
...process.env,
...Object.fromEntries(
Object.entries(checkedEnv).map(([key, value]) => [key, String(value)]),
),
};
// Use in your CDK stack
new MyStack(app, 'MyStack', stackProps);
```
### Error Handling
The library will throw an error if:
- The environment file cannot be found or read
- The file content doesn't match the provided schema
You can enable debug logging by setting the `DEBUG` environment variable:
```bash
DEBUG=true npm run start
```
## API Reference
### `getEnv`
Loads and validates environment configuration from a file.
#### Parameters
- `pathOfEnvFile`: `string | Array` - Path to the environment file
- `envSchema`: `z.ZodObject` - Zod schema for validating the environment configuration
#### Returns
- `z.infer` - The validated environment configuration with inferred types from the schema
#### Throws
- `Error` - If the file cannot be found or read
- `z.ZodError` - If the file content doesn't match the provided schema
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.