`tarkus-env-manager` is a lightweight TypeScript utility for safely validating and managing environment variables using [Zod](https://zod.dev/). It is designed for Node.js or other Javascript applications where strict validation and transformation of envi
npm install tarkus-env-managertarkus-env-manager is a lightweight TypeScript utility for safely validating and managing environment variables using Zod. It is designed for Node.js or other Javascript applications where strict validation and transformation of environment variables is critical.
โ
Automatically loads .env via dotenv inside the library โ no need to manually call dotenv.config() in your project.
* ๐ Strict validation of environment variables using Zod
* ๐ Supports value transformation (e.g., string to boolean, string to array)
* โ๏ธ Default values supported
* ๐งช Auto-validation during app startup
* ๐ ๏ธ Full integration with process.env
* ๐ฆ Built-in support for loading .env via dotenv
``bash
npm install tarkus-env-manager
`
> โ ๏ธ dotenv is required as a peer dependency and is automatically used inside the library.
`ts
import EnvironmentManager, { TypeEnv } from 'tarkus-env-manager';
const envSchema = TypeEnv.object({
// === APP CONFIG ===
APP_ENV: TypeEnv.enum(['dev', 'production', 'test']),
APP_DEBUG: TypeEnv.string()
.transform(val => val === 'true')
.pipe(TypeEnv.boolean()),
APP_URL: TypeEnv.string().url(),
APP_PORT: TypeEnv.string().default('8016'),
APP_STATIC_TOKEN: TypeEnv.string(),
// === JWT & TOKENS ===
APP_ACCESS_TOKEN_SECRET: TypeEnv.string(),
APP_REFRESH_TOKEN_SECRET: TypeEnv.string(),
APP_USER_DEFAULT_PASSWORD: TypeEnv.string(),
// === SERVICES ===
EXAMPLE_HOSTNAME: TypeEnv.string().url(),
// === DATABASE ===
DB_HOST: TypeEnv.string(),
DB_HOST_READ: TypeEnv.string(),
DB_HOST_PORT: TypeEnv.string().default('3306'),
DB_USERNAME: TypeEnv.string(),
DB_PASSWORD: TypeEnv.string(),
DB_DATABASE: TypeEnv.string(),
DB_PORT: TypeEnv.string().default('3306'),
// === KAFKA ===
KAFKA_CLIENT_ID: TypeEnv.string(),
KAFKA_BROKERS: TypeEnv.string().transform(val =>
val.split(',').map(b => b.trim()),
),
KAFKA_USERNAME: TypeEnv.string(),
KAFKA_PASSWORD: TypeEnv.string(),
KAFKA_USE_SSL: TypeEnv.string()
.transform(val => val === 'true')
.pipe(TypeEnv.boolean()),
});
`
`ts`
const EnvManager = new EnvironmentManager
const env = EnvManager.getEnv();
`ts`
export { EnvManager };
export default env;
* schema: A z.object({...}) schema that defines and validates the environment variables.process.env
* Automatically validates on initialization.
* Throws an error if validation fails.
* Returns the validated and transformed environment variables as an object.
* Explicitly checks for missing or empty environment variables.
* Throws an error listing missing keys.
* You do not need to manually call dotenv.config() โ it is automatically loaded within tarkus-env-manager..env
* Ensure your file is present in the root of your project..env
* Always make sure your matches your schema.
File`env
APP_ENV=dev
APP_DEBUG=true
APP_URL=http://localhost:3000
APP_STATIC_TOKEN=mytoken
APP_ACCESS_TOKEN_SECRET=secret1
APP_REFRESH_TOKEN_SECRET=secret2
APP_USER_DEFAULT_PASSWORD=defaultpass
EXAMPLE_HOSTNAME=https://example.com
DB_HOST=localhost
DB_HOST_READ=localhost
DB_USERNAME=root
DB_PASSWORD=secret
DB_DATABASE=mydb
KAFKA_CLIENT_ID=myclient
KAFKA_BROKERS=broker1:9092,broker2:9092
KAFKA_USERNAME=user
KAFKA_PASSWORD=pass
KAFKA_USE_SSL=true
`
`bash`
.
โโโ app/
โ โโโ configs/
โ โ โโโ EnvConfig.ts # Environment schema and validation logic
โ โโโ repositories/
โ โโโ KnexRepositoryBase.ts # Database bootstrap and teardown
โโโ app.ts # Express app instance
โโโ server.ts # App entry point
โโโ .env # Environment configuration file
โโโ README.md
`ts
const EnvManager = new EnvironmentManager
const env = EnvManager.getEnv();
export { EnvManager };
export default env;
`
`ts
EnvManager.check(); // Ensures no required variables are missing
const port = env.APP_PORT;
app.listen(port, () => {
logger.info(Running on http://localhost:${port});``
});
MIT License ยฉ 2025