\n\n\n\n## Introduction\n\n`@baginskicosta/environment` is a complete ecosystem for managing\n**environment variables**, focused and optimized for modern JavaScript\nruntimes such as **Node**, **Bun**, and **Deno**.\n\nIt provides specialized modules for each stage involved in processing\n`.env` files:\n\n- `core`: the foundation of the entire ecosystem. It is responsible for\n **compiler-time** inference of environment variables and works\n alongside validation libraries compatible with\n [Standard Schema V1][standard_schema].\n\n- `loader`: the loader and parser for `.env` files. It is responsible\n for analyzing **environment variables** contained in configuration\n files, taking into account the technical capabilities of each\n JavaScript runtime. It is designed to perform well in **serverless**\n environment and environments where minimizing **cold starts**\n is important.\n\n- `validator`: a minimal native validation library compatible with\n [Standard Schema V1][standard_schema]. It provides validation tools\n based on native TypeScript types and can be used alongside\n third-party libraries such as **Zod**, **Valibot**, and **ArkType**,\n as long as they implement the [Standard Schema V1][standard_schema]\n specification.\n\n- `preset`: an optional helper library containing **schemas** for\n commonly used tools, services, and SDKs in the modern JavaScript\n ecosystem. All schemas follow their maintainers original\n specifications and can be extended or used alongside external\n validation libraries through the `validator` module and the\n constructors provided by `core`.\n\n\n\n## Features\n\n- Zero external dependencies.\n- Strong compiler-time inference.\n- Comprehensive runtime handling.\n- Works with the major modern JavaScript runtimes.\n- Works with both TypeScript and JavaScript.\n- Minimal cold-start overhead.\n- Optional presets based on their maintainers specifications.\n- Easy extensibility and support for community-created presets.\n\n\n\n## Installation\n\n```bash\nbun add @baginskicosta/environment # bun package manager\n```\n\n```bash\nnpm install @baginskicosta/environment # node package manager\n```\n\n\n\n## Basic Usage\n\nBefore anything else, you need to define a schema for your **environment\nvariables**. For demonstration purposes, we will use a basic schema:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport { loadEnvFirst } from \"@baginskicosta/environment/loader\";\nimport { number, string } from \"@baginskicosta/environment/validator\";\n\nexport const ENVIRONMENT = defineEnvironment({\n runtimeEnv: loadEnvFirst([\".env.local\", \".env\"]),\n server: {\n DATABASE_URL: string({ min: 10, url: true }),\n PORT: number({ min: 1025, integer: true }),\n },\n})();\n```\n\nAs you can see, each part has a distinct but essential role in the\nconfiguration. Let's break down each part bellow.\n\n### Defining the Environment\n\nIn the example above, we call the `defineEnvironment` function exported\nby `core`. It is responsible for defining the shape of the environment\nvariables as well as controlling access between **server**, **client**\nand **shared** variables.\n\nTo define an empty environment, simply use:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\n\nexport const ENVIRONMENT = defineEnvironment({\n runtimeEnv: process.env,\n server: {},\n})();\n```\n\n### Defining Environment Variables\n\nBy default `core` analyses the variables loaded into `process.env` by\nthe JavaScript runtime. This behavior can be changed by explicitly\ndefining them through the `runtimeEnv` property:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\n\nexport const ENVIRONMENT = defineEnvironment({\n runtimeEnv: {\n DATABASE_URL: \"mongo://admin:admin@localhost:27017/\",\n PORT: 3000,\n },\n server: {},\n})();\n```\n\nWe recommend defining `runtimeEnv` using one of the environment varible\nloader methods instead of relying directly on `process.env`. You can\nuse either `loadEnv` or `loadEnvFirst` from the `loader` module:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport { loadEnv } from \"@baginskicosta/environment/loader\";\n\nexport const ENVIRONMENT = defineEnvironment({\n runtimeEnv: loadEnv(\".env.local\"),\n server: {\n /** ... */\n },\n})();\n```\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport { loadEnvFirst } from \"@baginskicosta/environment/loader\";\n\nexport const ENVIRONMENT = defineEnvironment({\n runtimeEnv: loadEnvFirst([\".env.local\", \".env\"]),\n server: {\n /** ... */\n },\n})();\n```\n\n### Defining the Schema\n\nThis library allows you to declare different types of **schemas** for\nthe **server**, **client** and **shared** environments.\\\nA schema can be defined using any validation library compatible with\n[Standard Schema V1][standard_schema] including **Zod**, **Valibot**,\nand **ArkType**.\n\nIf you prefer not to add additional dependencies to your project, you\ncan also use the build-in `validator` module. The native validator\nprovides the following validation types and configuration options:\n\n```typescript\nimport {\n array,\n boolean,\n enumOf,\n number,\n object,\n string,\n} from \"@baginskicosta/environment/validator\";\n\n// * define an array validation\nfunction array(\n definition: Readonly<{\n items: TItems;\n min?: number;\n max?: number;\n }>,\n): TArraySchema;\n\n// * define a boolean validation\nfunction boolean(\n definition?: Readonly<{\n coerce?: boolean;\n }>,\n): TBooleanSchema;\n\n// * define an enum validation\nfunction enumOf(\n values: T,\n): TEnumSchema;\n\n// * define a number validation\nfunction number(\n definition?: Readonly<{\n min?: number;\n max?: number;\n integer?: boolean;\n coerce?: boolean;\n }>,\n): TNumberSchema;\n\n// * defina an object validation\nfunction object(\n definition: Readonly<{\n shape: Readonly;\n strict?: boolean;\n }>,\n): TObjectSchema;\n\n// * define a string validation\nfunction string(\n definition?: Readonly<{\n min?: number;\n max?: number;\n pattern?: RegExp;\n email?: boolean;\n url?: boolean;\n trim?: boolean;\n }>,\n): TStringSchema;\n```\n\nAll validator support **optional schemas** by calling `.optional` after\nthe main declaration.\\\nThe behavior of optional values depend on the `emptyStringAsUndefined`\nconfiguration.\\\nWhen set to `true`, undeclared or empty optional variables are treated\nas `undefined`.\\\nOtherwise, they are recognized as **empty strings (`\"\"`)**.\n\nThese validators are sufficient for most environments because they cover\nthe main native types, which are automatically analysed and transformed\nwhile loading **environment variables**.\\\nThey also be used alongside other validation libraries compatible with\n[Standard Schema V1][standard_schema].\n\n### Error Handling\n\nThe `core` module provides functions through `defineEnvironment` for\nhandling **validation errors** and **invalid access**. They can be\nconfigured as follows:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\n\nexport const ENVIRONMENT = defineEnvironment({\n /** ... */\n\n // * handles validation failures\n onValidationError?: (\n issues: Readonly\n ) => never,\n\n // * handle access to unavailable environment variables\n onInvalidAccess?: (variable: string) => never,\n\n /** ... */\n})();\n```\n\n### Running the Analysis and Using Variables\n\nThe `defineEnvironment` function from the `core` module does not\nautomatically process and analyse **environment varibles**. Instead,\nit returns a **factory** that must be called to start the process.\nThis design prevents the environment from being processed at an\ninappropriate time and avoids unnecessary work at runtime.\n\nThe returned **factory** can be used in two different ways: through a\nnormal function call, or through a selective call that allows you to\nfilter and select only the **environment varibles** you need. This is\nespecially useful when using **extensions** or when sharing the same\nenvironment configuration across different parts of an applicaiton.\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport { VercelSystem } from \"@baginskicosta/environment/preset\";\n\nconst BASE_ENVIRONMENT = defineEnvironment({\n extends: [VercelSystem()],\n runtimeEnv: process.env,\n server: {\n MY_OWN_VARIABLE: string({ min: 10 }).optional(),\n },\n});\n\n// * merges all variables from the 'VercelSystem' preset\n// * and developer-defined variables\nexport const FULL_ENVIRONMENT = BASE_ENVIRONMENT();\n\n// * preforms a partial merge containing only the variables\n// * explicitly required by the developer\nexport const FILTERED_ENVIRONMENT = BASE_ENVIRONMENT([\n \"VERCEL\",\n \"CI\",\n \"MY_OWN_VARIABLE\",\n]);\n```\n\n### Using Extensions\n\nThe `core` module allows you to define extensions for **environment\nvariables** using schemas declared with validation libraries compatible\nwith [Standard Schema V1][standard_schema]. Extensions are defined\nthrough the `defineEnvironment` **factory** and allow the community to\ncreate their own collections of presets for different use cases.\n\nA good example is the build-in `preset` module, which provides\ndefinitions for **environment variables** used by commonly adopted\nlibraries, SDKs, and services in the JavaScript ecosystem.\n\nTo use an **extension**, simply instantiate it through the `extends`\npropery of `defineEnvironment`:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport {\n GoogleOAuth,\n VercelSystem,\n Supabase,\n} from \"@baginskicosta/environment/preset\";\n\nexport const ENVIRONMENT = defineEnvironment({\n extends: [VercelSystem(), GoogleOAuth(), Supabase()],\n server: {\n /** ... */\n },\n})();\n```\n\nExtensions can be used to build complete or partial environment because\nthey are instances of the factory returned by `defineEnvironment`.\nHowever, they must not be restricted through the `TEnvironmentFactory`\ntype if partial construction is required, as that type only allows\ncomplete constructions.\n\nTo create an extension, simply export its factory:\n\n```typescript\nimport defineEnvironment from \"@baginskicosta/environment\";\nimport type { TEnvironmentFactory } from \"@baginskicosta/environment/preset\";\n\nexport const MY_EXTENSION: TEnvironmentFactory<{\n MY_SHARED_VARIABLE: number;\n MY_SERVER_VARIABLE?: string;\n PUBLIC_CLIENT_VARIABLE: boolean;\n}> = defineEnvironment({\n shared: {\n MY_SHARED_VARIABLE: number({ min: 10, integer: true }),\n },\n server: {\n MY_SERVER_VARIABLE: string({ min: 1 }).optional(),\n },\n clientPrefix: \"PUBLIC_\",\n client: {\n PUBLIC_CLIENT_VARIABLE: boolean({ coerce: true }),\n },\n});\n```\n\n**Important:** as a best pratice, all exported extensions should be\ninstances of the factory returned by `defineEnvironment`. They should\nnot be called directly, as doing so would trigger unnecessary processing.\n\nWhen using `TEnvironmentFactory`, keep in mind that variables marked as\n**optional** by validatiors must algo be use the `?:` token in their\ntype declaration, Otherwise, a type incompatibility error will be raised.\n\n\n\n## Native Extensions\n\nThe `preset` module provides a collection of **schemas** covering\ncommonly used libraries, SDKs, services, and platforms in modern\nJavaScript development. All presets follow the specifications provided\nby their respective maintainers and are designed to remain easy to audit.\n\nThe following **native extensions** are exported by the `preset` module,\nalong with their respective categories and links to the maintainers\nofficial documentation:\n\n| Maintainer | Group | Native Extension |\n| ------------------- | ----------- | --------------------------------------------- |\n| Amazon Web Services | `cloud` | [`WebServicesLambda`][ex_aws_lambda] |\n| Amazon Web Services | `cloud` | [`WebServicesCLI`][ex_aws_cli] |\n| Google | `cloud` | [`GoogleOAuth`][ex_google_oauth] |\n| Google | `cloud` | [`GoogleFirebase`][ex_google_firebase] |\n| Microsoft Azure | `cloud` | [`AzureWithSecret`][ex_azure_sdk] |\n| Microsoft Azure | `cloud` | [`AzureWithCertificate`][ex_azure_sdk] |\n| Microsoft Azure | `cloud` | [`AzureBlobStorage`][ex_azure_blob] |\n| Microsoft Azure | `cloud` | [`AzureServiceBusWithSecret`][ex_azure_bus] |\n| Microsoft Azure | `cloud` | [`AzureServiceBus`][ex_azure_bus] |\n| Cloudflare | `platforms` | [`CloudflareWrangler`][ex_cloudf_wrangler] |\n| Cloudflare | `platforms` | [`CloudflareHyperdrive`][ex_cloudf_hyper] |\n| Cloudflare | `platforms` | [`CloudflareContainers`][ex_cloudf_container] |\n| Fly.io | `platforms` | [`FlyMachineRuntime`][ex_flyio] |\n| GitHub | `platforms` | [`GitHubActions`][ex_gh_actions] |\n| GitHub | `platforms` | [`GitHubCodespaces`][ex_gh_codespaces] |\n| GitLab | `platforms` | [`GitLabCI`][ex_gitlab] |\n| Netlify | `platforms` | [`Netlify`][ex_netlify] |\n| Railway | `platforms` | [`Railway`][ex_railway] |\n| Render | `platforms` | [`Render`][ex_render] |\n| Render | `platforms` | [`RenderWebServices`][ex_render_ws] |\n| Vercel | `platforms` | [`VercelSystem`][ex_vercel_system] |\n| Vercel | `platforms` | [`VercelBlob`][ex_vercel_blob] |\n| Vercel | `platforms` | [`VercelAI`][ex_vercel_ai] |\n| Vercel | `platforms` | [`VercelNextJS`][ex_vercel_frame] |\n| Vercel | `platforms` | [`VercelNuxt`][ex_vercel_frame] |\n| Vercel | `platforms` | [`VercelVite`][ex_vercel_frame] |\n| Auth0 | `services` | [`Auth0`][ex_auth0] |\n| NextAuth | `services` | [`NextAuth`][ex_nextauth] |\n| Clerk | `services` | [`Clerk`][ex_clerk] |\n| Supabase | `services` | [`Supabase`][ex_supabase] |\n| Neon | `services` | [`Neon`][ex_neon] |\n| MongoDB | `services` | [`MongoDB`][ex_mongo] |\n| Upstash | `services` | [`UpstashRedis`][ex_upstash_redis] |\n| Upstash | `services` | [`UpstashVector`][ex_upstash_vector] |\n| Upstash | `services` | [`UpstashQStash`][ex_upstash_qstash] |\n| Upstash | `services` | [`UpstashSearch`][ex_upstash_search] |\n| Upstash | `services` | [`UpstashBox`][ex_upstash_box] |\n\nIn addition to third-party **extensions**, we maintain a set of base\n**schemas** for capabilities commonly required by development\nenvironments. These serve as building blocks for some of the\nnative extensions:\n\n| Maintainer | Group | Native Extension |\n| -------------- | -------------- | ------------------------ |\n| Baginski Costa | `capabilities` | [`NeedSecret`][ex_lib] |\n| Baginski Costa | `capabilities` | [`NeedAuth`][ex_lib] |\n| Baginski Costa | `capabilities` | [`NeedDatabase`][ex_lib] |\n| Baginski Costa | `capabilities` | [`NeedEmail`][ex_lib] |\n\n**Important:** when upgrading the library to a newer version, it is\nrecommended to review the changes made to the native extensions based\non third-party specifications. As their upstream services and tools\nenvolve, those changes may also be reflected in the `preset` module.\n\n\n\n## Support My Work\n\nIf this this project, or any of my other projects, has been useful to\nyou, your team, or your company, consider supporting my work.\nMaintaining open-source projects take time. Support helps me keep\nworking on improvements, fixes, documentation, and new features while\ncontinuing to make projects available to everyone.\n\nIf you would like to directly support the development of my projects,\ntou can become a supported on Patreon:\n\n[![Sponsor on Patreon][badge_patreon]][me_patreon]\n\nEven a small contribution helps. It gives me more time to work on\nopen-source projects and keep them maintained instead of having to\ntreat them as something I can only work on in my spare time.\n\n### Follow My Work\n\nYou can also follow me on social media. This is another simple way to\nsupport my work, keep up with new projects and content, and help more\ndevelopers discover what I am building.\n\n[![Follow on YouTube][badge_youtube]][me_youtube]\n[![Follow on Instagram][badge_insta]][me_insta]\n[![Follow on Twitch][badge_twitch]][me_twitch]\n\n\n\n## Supporters\n\n> Want to support the development of open-source projects?\\\n> Become a [supporter on Patreon][me_patreon] and have your name or\n> company featured in this and future repositories and projects.\n\nI want to sincerely thank everyone who supports my work through\n[Patreon][me_patreon]. Your support gives me the time and motivation\nto keep building, maintaining, and improving these projects.\n\nThank you for supporting my work and helping me keep open-source\ndevelopment moving forward.\n\n| Badge | Sponsor |\n| ----------------- | ------------------ |\n| :heart: SUPPORTER | Emerson Luiz Costa |\n","readmeFilename":"README.md","_rev":"1-1ed7c4bef3cc64f2cecaf55fac725775"}
![\"Instagram\"](\"https://shields.io/badge/INSTAGRAM-303030?logo=instagram&style=for-the-badge&labelColor=2c488c&logoColor=white\"){kind=icon}
\n \n \n