{"id":30850914,"url":"https://github.com/shahradelahi/process-venv","last_synced_at":"2025-09-07T06:40:20.434Z","repository":{"id":311830516,"uuid":"885121132","full_name":"shahradelahi/process-venv","owner":"shahradelahi","description":"🛡️ Securely load, validate, and manage environment variables in TypeScript.","archived":false,"fork":false,"pushed_at":"2025-09-06T21:45:56.000Z","size":151,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-06T23:26:50.745Z","etag":null,"topics":["dotenv","env","environment-variables","nodejs","process","standard-schema","validation"],"latest_commit_sha":null,"homepage":"https://npmjs.com/process-venv","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shahradelahi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-08T01:53:47.000Z","updated_at":"2025-09-06T21:44:54.000Z","dependencies_parsed_at":"2025-08-27T06:18:09.973Z","dependency_job_id":"8a38d2c8-9929-47b7-b58f-bfa6b402c91a","html_url":"https://github.com/shahradelahi/process-venv","commit_stats":null,"previous_names":["shahradelahi/process-venv"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/shahradelahi/process-venv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahradelahi%2Fprocess-venv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahradelahi%2Fprocess-venv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahradelahi%2Fprocess-venv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahradelahi%2Fprocess-venv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shahradelahi","download_url":"https://codeload.github.com/shahradelahi/process-venv/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shahradelahi%2Fprocess-venv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274005336,"owners_count":25205934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dotenv","env","environment-variables","nodejs","process","standard-schema","validation"],"created_at":"2025-09-07T06:40:17.802Z","updated_at":"2025-09-07T06:40:20.425Z","avatar_url":"https://github.com/shahradelahi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# process-venv\n\n[![CI](https://github.com/shahradelahi/process-venv/actions/workflows/ci.yml/badge.svg?branch=main\u0026event=push)](https://github.com/shahradelahi/process-venv/actions/workflows/ci.yml)\n[![NPM Version](https://img.shields.io/npm/v/process-venv.svg)](https://www.npmjs.com/package/process-venv)\n[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](/LICENSE)\n[![Install Size](https://packagephobia.com/badge?p=process-venv)](https://packagephobia.com/result?p=process-venv)\n\nA robust and lightweight TypeScript library for securely loading, validating, and managing environment variables, preventing unintended access by third-party dependencies.\n\n---\n\n- [Motivation](#-motivation)\n- [Features](#-features)\n- [Installation](#-installation)\n- [Usage](#-usage)\n- [Documentation](#-documentation)\n- [Contributing](#-contributing)\n- [License](#license)\n\n## 🤔 Motivation\n\nIn modern applications, especially those with a large number of dependencies, there's a significant risk of sensitive environment variables (like API keys, database credentials, etc.) being inadvertently accessed or logged by \"shady\" or compromised third-party packages. The traditional approach of loading all `.env` variables directly into `process.env` exposes your entire configuration to every part of your application's dependency tree.\n\n`process-venv` addresses this by providing a \"virtual environment\" for your application's configuration. It ensures that:\n\n1.  **Isolation:** Only explicitly \"shared\" environment variables are exposed to `process.env`. All other variables are kept in memory within the `createEnv` instance, accessible only through its properties.\n2.  **Validation:** All environment variables are rigorously validated against a [Standard Schema](https://standardschema.dev) compliant schema at application startup, catching missing or malformed configurations early. While the examples use Zod, `process-venv` is designed to work with any Standard Schema compliant validator (e.g., Valibot, ArkType).\n3.  **Immutability:** The environment variables are immutable after creation, enhancing predictability and preventing accidental runtime modifications.\n\nThis approach significantly enhances the security and reliability of your application's environment management.\n\n## ✨ Features\n\n- **Secure Isolation**: Prevents unintended access to sensitive environment variables by third-party dependencies.\n- **Standard Schema Validation**: Enforces strict schema validation for all environment variables at runtime, allowing you to use any compliant validator (e.g., Zod, Valibot, ArkType).\n- **Flexible Loading**: Load from `.env` files or directly from an existing object (e.g., from a secret vault).\n- **Immutability**: Environment variables are immutable after creation.\n- **Lightweight**: Minimal footprint with zero runtime dependencies beyond `dotenv` (optional) and your chosen Standard Schema compliant validator.\n- **TypeScript First**: Written entirely in TypeScript with strong type safety.\n\n## 📦 Installation\n\n```bash\npnpm install process-venv\n```\n\n## 📖 Usage\n\n### Loading from `.env` files\n\nIt is recommended to define your environment schema and initialize `createEnv` in a dedicated file (e.g., `src/env.ts`) and then import the `venv` instance where needed.\n\n```typescript\n// -- src/env.ts\n\nimport { createEnv } from 'process-venv';\nimport * as z from 'zod';\n\nexport const venv = createEnv({\n  schema: {\n    NODE_ENV: z\n      .enum(['development', 'production', 'test'])\n      .default('development'),\n    PORT: z.coerce.number().default(3000),\n    DATABASE_URL: z.string().url(),\n    API_KEY: z.string(), // This will be private by default\n    SHARED_SECRET: z.string(), // This will be shared\n  },\n  shared: ['NODE_ENV', 'PORT', 'SHARED_SECRET'],\n  // Optional dotenv options:\n  // path: ['.env.local', '.env'],\n});\n```\n\nThen, in your application's entry point (e.g., `src/index.ts`):\n\n```typescript\n// -- src/index.ts\n\nimport { venv } from './env';\n\n// Access shared variables via process.env (e.g., for frameworks)\nconsole.log('NODE_ENV from process.env:', process.env.NODE_ENV);\n\n// Access all variables securely via the venv instance\nconsole.log('API_KEY from venv:', venv.API_KEY);\nconsole.log('PORT from venv:', venv.PORT);\n\n// process.env.API_KEY will be undefined\nconsole.log('API_KEY from process.env:', process.env.API_KEY);\n```\n\n### Loading from an external object\n\nSimilarly, for loading from an external object, you can define and initialize your `venv` instance in `src/env.ts`:\n\n```typescript\n// -- src/env.ts\n\nimport { createEnv } from 'process-venv';\nimport { z } from 'zod';\n\nconst myExternalConfig = {\n  NODE_ENV: 'production',\n  PORT: '8080',\n  DATABASE_URL: 'postgresql://user:pass@host:port/db',\n  API_KEY: 'my-super-secret-key-from-vault',\n};\n\nexport const venv = createEnv(\n  {\n    schema: {\n      NODE_ENV: z.enum(['development', 'production', 'test']),\n      PORT: z.coerce.number(),\n      DATABASE_URL: z.string().url(),\n      API_KEY: z.string(),\n    },\n    shared: ['NODE_ENV', 'PORT'],\n  },\n  myExternalConfig\n);\n```\n\nAnd then use it in `src/index.ts`:\n\n```typescript\n// -- src/index.ts\n\nimport { venv } from './env';\n\nconsole.log('API_KEY from venv:', venv.API_KEY);\nconsole.log('NODE_ENV from process.env:', process.env.NODE_ENV);\n```\n\n## 📚 Documentation\n\nFor all configuration options, please see [the API docs](https://www.jsdocs.io/package/process-venv).\n\n## 🤝 Contributing\n\nWant to contribute? Awesome! To show your support is to star the project, or to raise issues on [GitHub](https://github.com/shahradelahi/process-venv)\n\nThanks again for your support, it is much appreciated! 🙏\n\n## License\n\n[MIT](/LICENSE) © [Shahrad Elahi](https://github.com/shahradelahi) and [contributors](https://github.com/shahradelahi/process-venv/graphs/contributors).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahradelahi%2Fprocess-venv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshahradelahi%2Fprocess-venv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshahradelahi%2Fprocess-venv/lists"}