{"id":17807,"library":"middy-env","title":"Middy Environment Variable Middleware","description":"middy-env is a middleware for the middy framework, specifically designed to parse and inject environment variables into AWS Lambda function handlers. It's currently at version 2.0.0, which aligns with the major version 2.x of the core middy framework, ensuring compatibility with the latest middy features and architecture. This package provides robust configuration management for serverless functions, allowing developers to define required environment variables, specify their expected types (string, int, float, bool), and provide fallback values to prevent runtime errors. A key differentiator is its ability to assign parsed variables directly to the Lambda `context` object by default, rather than polluting the global `process.env`, offering a cleaner and more isolated configuration scope per invocation. It also supports optional caching of parsed values to optimize performance for subsequent warm invocations, with configurable expiry times. The package maintains a stable release cadence, typically aligning with major middy framework updates.","status":"active","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/chrisandrews7/middy-env","tags":["javascript","middy","middleware","lambda","env","config","var","environment"],"install":[{"cmd":"npm install middy-env","lang":"bash","label":"npm"},{"cmd":"yarn add middy-env","lang":"bash","label":"yarn"},{"cmd":"pnpm add middy-env","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; middy-env is middleware for the middy framework.","package":"middy","optional":false}],"imports":[{"note":"The middleware function is the default export. For CommonJS environments, use `const env = require('middy-env');` directly to get the middleware function.","wrong":"const { env } = require('middy-env');","symbol":"env","correct":"import env from 'middy-env';"},{"note":"While `middy-env`'s quickstart uses `require('middy')` for backward compatibility or CJS setups, `middy` v2.x (which `middy-env` v2.x supports) typically recommends `import middy from '@middy/core';` for ESM and modern CJS usage.","wrong":"const middy = require('middy');","symbol":"middy","correct":"import middy from '@middy/core';"}],"quickstart":{"code":"const middy = require('middy');\nconst env = require('middy-env');\n\nconst handler = async (event, context) => {\n  // Access variables directly from context object\n  const firstName = context.firstName ?? 'Guest';\n  const lastName = context.lastName ?? '';\n\n  return {\n    statusCode: 200,\n    body: `Hello ${firstName} ${lastName}`\n  };\n};\n\nmodule.exports = middy(handler)\n  .use(env({\n    names: {\n      firstName: ['FIRST_NAME', 'string', 'World'], // 'World' is fallback if FIRST_NAME env var is missing\n      lastName: 'LAST_NAME' // Will throw ReferenceError if LAST_NAME is missing and no fallback\n    },\n    cache: true,\n    cacheExpiryInMillis: 3600000 // Cache for 1 hour (3,600,000 milliseconds)\n  }));","lang":"javascript","description":"Demonstrates how to apply the `middy-env` middleware to a Lambda handler, parsing `FIRST_NAME` and `LAST_NAME` environment variables and injecting them into the `context` object, with caching enabled."},"warnings":[{"fix":"Upgrade your middy framework to v2.x (`npm install @middy/core@^2`) or downgrade middy-env to v1.x (`npm install middy-env@^1`).","message":"middy-env v2.x introduces support for middy v2.x. If your project uses middy v1.x, you must use middy-env v1.x to ensure compatibility.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always provide a fallback value in your `names` configuration (e.g., `['KEY', 'string', 'defaultValue']`) or guarantee the environment variable is always present in your deployment environment.","message":"Environment variables specified in the `names` option will cause a `ReferenceError` if they are not set in the environment and no fallback value is provided in the configuration.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you require the parsed variables to be available on `process.env`, set the `setToContext` option to `false` in your middleware configuration (e.g., `env({ names: { ... }, setToContext: false })`).","message":"By default, parsed environment variables are assigned to the Lambda `context` object. They are not added to `process.env`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Update your `middy-env` configuration to include a fallback value for `lastName` (e.g., `lastName: ['LAST_NAME', 'string', '']`) or ensure the `LAST_NAME` environment variable is correctly set in your Lambda function's environment.","cause":"The environment variable 'LAST_NAME' was not found in the Lambda execution environment, and no fallback value was specified in the `middy-env` middleware configuration for `lastName`.","error":"ReferenceError: LAST_NAME is not defined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}