{"id":16208,"library":"scenv-zod","title":"scenv-zod","description":"scenv-zod is a utility library that integrates the Zod schema validation library with scenv, a package for managing environment variables and configuration. It provides a `parser` function that allows developers to define robust validation and coercion rules for their configuration variables using Zod schemas. This ensures type safety and data integrity when reading values from environment variables, CLI arguments, or default settings within scenv. Currently at version 0.4.0, it's a relatively new and actively developed package, primarily focused on enhancing `scenv`'s parsing capabilities. It differentiates itself by leveraging Zod's powerful schema definition language for parsing, offering granular control over data types, transformations (e.g., string to number/boolean), and comprehensive error handling. This makes it a strong choice for applications requiring strict and predictable configuration validation, reducing runtime errors caused by malformed environment variables. Its concise API simplifies complex validation logic, promoting cleaner and more maintainable configuration codebases.","status":"active","version":"0.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/PKWadsy/scenv","tags":["javascript","scenv","zod","validation","typescript"],"install":[{"cmd":"npm install scenv-zod","lang":"bash","label":"npm"},{"cmd":"yarn add scenv-zod","lang":"bash","label":"yarn"},{"cmd":"pnpm add scenv-zod","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for defining and managing environment variables.","package":"scenv","optional":false},{"reason":"Core dependency for schema definition, validation, and parsing.","package":"zod","optional":false}],"imports":[{"note":"The primary named export from scenv-zod for creating scenv-compatible Zod parsers.","wrong":"const { parser } = require('scenv-zod');","symbol":"parser","correct":"import { parser } from 'scenv-zod';"},{"note":"scenv is a peer dependency and must be imported separately for variable definition.","wrong":"const scenv = require('scenv');","symbol":"scenv","correct":"import { scenv } from 'scenv';"},{"note":"Zod is a peer dependency and its schema builder 'z' must be imported separately to define validation schemas.","wrong":"const z = require('zod');","symbol":"z","correct":"import { z } from 'zod';"}],"quickstart":{"code":"import { scenv } from \"scenv\";\nimport { parser } from \"scenv-zod\";\nimport { z } from \"zod\";\n\nconst port = scenv(\"Port\", {\n  key: \"port\",\n  env: \"PORT\",\n  default: 3000,\n  parser: parser(z.coerce.number().min(1).max(65535))\n});\n\nconst debug = scenv(\"Debug\", {\n  key: \"debug\",\n  env: \"DEBUG\",\n  default: false,\n  parser: parser(\n    z.union([z.boolean(), z.literal(\"true\"), z.literal(\"false\")])\n      .transform((v) => v === true || v === \"true\")\n  )\n});\n\n// Simulate environment variables for demonstration\nprocess.env.PORT = process.env.PORT ?? '8080';\nprocess.env.DEBUG = process.env.DEBUG ?? 'true';\n\nasync function runConfig() {\n  try {\n    const portNum = await port.get();   // number\n    const isDebug = await debug.get();  // boolean\n    console.log(`Application Port: ${portNum} (Type: ${typeof portNum})`);\n    console.log(`Debug Mode: ${isDebug} (Type: ${typeof isDebug})`);\n  } catch (error) {\n    if (error instanceof z.ZodError) {\n      console.error('Validation failed:', error.errors);\n    } else {\n      console.error('An unexpected error occurred:', error);\n    }\n  }\n}\n\nrunConfig();","lang":"typescript","description":"Demonstrates defining environment variables with Zod validation, coercing strings to numbers and booleans, and handling potential errors during parsing using `scenv` and `scenv-zod`."},"warnings":[{"fix":"Always use Zod's `z.coerce.<type>()` methods (e.g., `z.coerce.number()`, `z.coerce.boolean()`) or explicit `.transform()` to convert string inputs to the desired type within your schema.","message":"Environment variables, CLI arguments, and context values are always read as strings by `scenv`. Direct Zod schema validation for non-string types (e.g., `z.number()`, `z.boolean()`) will fail unless proper coercion is applied.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use a `try...catch` block around `await variable.get()` to handle validation failures, or prefer `await variable.safeGet()` which returns a `{ success: boolean, data?, error? }` object, allowing for explicit error checking without exceptions.","message":"The `.get()` method from `scenv` (when using a scenv-zod parser) will throw a `ZodError` if validation fails. This can lead to unhandled promise rejections if not caught.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Regularly review the `zod` migration guide when upgrading its major version. Thoroughly test all configuration variable parsers after any `zod` or `scenv-zod` update.","message":"Major version updates of `zod` itself may introduce breaking changes to schema definition or validation behavior that could impact existing `scenv-zod` parsers.","severity":"breaking","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Inspect the `error.errors` array in the `ZodError` for specific validation issues. Ensure string inputs are correctly coerced (e.g., `z.coerce.number()`) and that all rules (e.g., `min`, `max`, `email`) are met by the provided value.","cause":"The value retrieved for a configuration variable (from env, CLI, or default) does not conform to the defined Zod schema.","error":"ZodError: Invalid input"},{"fix":"Install the required peer dependencies using your package manager: `npm install scenv zod` or `pnpm add scenv zod`.","cause":"The peer dependencies `scenv` or `zod` are not installed in the project, or they are not resolvable.","error":"Error: Cannot find module 'scenv' or 'zod'"},{"fix":"Verify that `import { scenv } from 'scenv';` is present and that the `scenv()` function is called with valid arguments, returning a variable object before `.get()` is invoked.","cause":"The `scenv` function or variable definition was not correctly executed or imported, resulting in an undefined variable object when `.get()` is called.","error":"TypeError: Cannot read properties of undefined (reading 'get')"}],"ecosystem":"npm"}