@valentino.chiola/safe-vars v1.0.4

Welcome to @valentino.chiola/safe-vars, a wrapper for dotenv.config() that parses the result and sets the values in process.env

Installation

To install use one of the following commands:

npm i @valentino.chiola/safe-vars

pnpm i @valentino.chiola/safe-vars

yarn add @valentino.chiola/safe-vars

Basic usage

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
  VARIABLE2: z.string(),
  BOOLEAN: z.coerce.boolean()
});

safeVars(schema)

console.log(process.env)

If in your .env file you have declared VARIABLE1 and VARIABLE2, it won't throw an error.

Note: any extra variables in your .env, that are not present in the schema, will be removed. Note: if the BOOLEAN variable is not defined, zod will cast it to false.

Options

• inject: If true, the variables will be injected in the process.env object. Default: true

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

export const env = safeVars(schema, { inject: false })

console.log(env.VARIABLE1) // VARIABLE 1
console.log(process.env.VARIABLE1) // undefined

• log: If true, the variables will be logged in the console. Default: false. Also can be an object with an only property which is an array of the variables that you want to log. Warning: This option should be used for debugging purposes only.

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

safeVars(schema, { log: true })

or:

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
  VARIABLE2: z.string(),
  SUPER_SECRET: z.string()
});

safeVars(schema, {
  log: {
    only: ["VARIABLE1", "VARIABLE2"],
  },
});

• throw: If false, it won't throw an error if the variables are not defined in the .env file, but all the variables would be optional. Default: true

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

safeVars(schema, { throw: false });

The type of env.VARIABLE1 will be string | undefined

• onSuccess: Callback function to be executed if all environment variables are successfully validated.

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

safeVars(schema, {
  onSuccess: (env) => console.log("🚀 Envs loaded!"),
});

• onError: Callback function to be executed if there are errors in the validation.

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

safeVars(schema, {
  onError: (errors) => console.error("❌ Error loading envs", errors),
});

• dotenv: An object that represents the options for the dotenv package.

  • path: You can use the path key to determine witch .env file should be parsed. This is useful for testing.

  import safeVars, { z } from "@valentino.chiola/safe-vars";
  
  const schema = z.object({
    VARIABLE1: z.string(),
  });
  
  safeVars(schema, {
    dotenv: {
      path: ".env.test",
    }
  });

Typed Envs

The are two ways to have your envs typed.

• declare module:

import safeVars, { z } from "@valentino.chiola/safe-vars";

const schema = z.object({
  VARIABLE1: z.string(),
});

safeVars(schema);

declare global {
  module NodeJS {
    interface ProcessEnv extends z.infer<typeof schema> {}
  }
}  

• return value:

Instead of using process.env you can use the safeVars's return value.

const schema = z.object({
  VARIABLE1: z.string(),
});

export const env = safeVars(schema, { inject: false });

The type of env.VARIABLE1 will be string

Contribution

Contributions are welcome! To contribute:

1. Fork this repository.
2. Create a branch with a meaningful description.
3. Make the desired changes.
4. Update the documentation if necessary.
5. Open a Pull Request to the main branch.

If you find an issue or have a suggestion to improve the project, feel free to open an issue.

License

This project is licensed under the MIT License.