@tzvipm.dev/env

v0.1.1

Published

6 months ago

Type-safe environment variable management for TypeScript applications

0High
0Medium
0Low

environment env config typescript validation type-safe environment-variables dotenv configuration

pnpm add @tzvpm.dev/env

The problem

Managing environment variables in modern TypeScript applications is painful:

No type safety - everything is string | undefined
No validation - runtime errors when variables are missing
No clear separation between server and client variables
No IDE autocomplete

This solution

@tzvpm.dev/env provides a type-safe, validated approach to environment variables with clear client/server separation and excellent developer experience.

Usage

Basic Usage

import { Env } from '@tzvpm.dev/env';

// Create your environment configuration
const env = Env.from(process.env);

// Define and use environment variables with type safety
const port = env.int('PORT').withFallback(3000);
const apiUrl = env.string('API_URL').required();
const isDev = env.bool('NODE_ENV').equals('development');

// Validate all variables at startup
env.validate(); // Throws if required variables are missing

Client/Server Separation

Keep your secrets safe with explicit client/server separation:

// server.ts
const env = Env.from(process.env);

// Server-only variables (default)
const databaseUrl = env.string('DATABASE_URL').required();
const apiSecret = env.string('API_SECRET').required();

// Explicitly client-safe variables
const publicApiUrl = env.string('NEXT_PUBLIC_API_URL').required().clientSafe();
const appName = env.string('APP_NAME').withFallback('My App').clientSafe();

// Serialize client-safe config for the browser
const clientConfig = env.renderToString();

// client.ts
import { Env } from '@tzvpm.dev/env/client';

// Hydrate from server-rendered config
const env = Env.hydrate(window.__ENV__);

// Access client-safe variables
const apiUrl = env.string('NEXT_PUBLIC_API_URL').parse();

// This throws an error - no access to server-only variables!
const secret = env.string('API_SECRET').parse(); // ❌ Error!

// app/layout.tsx (Next.js example)
export default function RootLayout({ children }) {
	return (
		<html>
			<head>
				<script
					dangerouslySetInnerHTML={{
						__html: `window.__ENV__ = ${env.renderToString()};`,
					}}
				/>
			</head>
			<body>{children}</body>
		</html>
	);
}

Type Safety

Get full TypeScript support with inferred types:

const env = Env.from(process.env);

// TypeScript knows these types!
const port = env.int('PORT').required(); // number
const name = env.string('APP_NAME').required(); // string
const debug = env.bool('DEBUG').withFallback(false); // boolean

// Use the values with confidence
server.listen(port); // ✅ TypeScript knows port is a number

Features

🎯 Type-safe - Full TypeScript support with inferred types
🔒 Secure - Clear separation between server and client variables
✅ Validated - Fail fast with helpful error messages
🚀 Fast - Zero dependencies, minimal overhead
🧩 Flexible - Works with any framework or runtime
📝 Developer friendly - Great error messages and IDE support

Contributing

This project uses automated releases. To contribute:

Create a feature branch
Make your changes
Run pnpm changeset to document your changes
Submit a PR

See RELEASING.md for detailed information about the release process.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme