Middy Environment Variable Middleware

2.0.0 verified Thu Apr 23 auth: no javascript

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.

Common errors

error ReferenceError: LAST_NAME is not defined ↓

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`.

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.

Warnings

breaking 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. ↓

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`).

gotcha 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. ↓

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.

gotcha By default, parsed environment variables are assigned to the Lambda `context` object. They are not added to `process.env`. ↓

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 })`).

Install

npm install middy-env

yarn add middy-env

pnpm add middy-env

Imports

env
wrong
```
const { env } = require('middy-env');
```
correct
```
import env from 'middy-env';
```
The middleware function is the default export. For CommonJS environments, use `const env = require('middy-env');` directly to get the middleware function.
middy
wrong
```
const middy = require('middy');
```
correct
```
import middy from '@middy/core';
```
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.

Quickstart

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.

const middy = require('middy');
const env = require('middy-env');

const handler = async (event, context) => {
  // Access variables directly from context object
  const firstName = context.firstName ?? 'Guest';
  const lastName = context.lastName ?? '';

  return {
    statusCode: 200,
    body: `Hello ${firstName} ${lastName}`
  };
};

module.exports = middy(handler)
  .use(env({
    names: {
      firstName: ['FIRST_NAME', 'string', 'World'], // 'World' is fallback if FIRST_NAME env var is missing
      lastName: 'LAST_NAME' // Will throw ReferenceError if LAST_NAME is missing and no fallback
    },
    cache: true,
    cacheExpiryInMillis: 3600000 // Cache for 1 hour (3,600,000 milliseconds)
  }));