eslint-plugin-no-process-env

eslint-plugin-no-process-env

Disallow direct process.env access in application code and enforce a centralized environment configuration pattern.

Why would I want this?

Every use of process.env in application code is a dependency on your external environment, and those dependencies are often unsatisfied at runtime, lack validation, and have inconsistent fallbacks.

It's generally a good practice to centralize env var access into a single configuration file which makes them explicit and self-documenting, and creates an opportunity to validate, coerce types, and set default values where appropriate.

This rule won't help your app crash less, but it will help it crash earlier and more loudly!

Install

npm i -D eslint eslint-plugin-no-process-env
yarn add -D eslint eslint-plugin-no-process-env
pnpm add -D eslint eslint-plugin-no-process-env
bun add -d eslint eslint-plugin-no-process-env

Tested with ESLint 8.57+, 9.x, and 10 alpha. Node 14.17+ for ESLint 8, 18.18+ for ESLint 9, 20.19+ for ESLint 10.

Usage (flat config, ESLint 9+/10)

// eslint.config.mjs
import noProcessEnv from "eslint-plugin-no-process-env";

export default [
  {
    plugins: { "no-process-env": noProcessEnv },
    rules: {
      "no-process-env/no-process-env": "error",
    },
  },
];

Usage (eslintrc, ESLint 8)

// .eslintrc.cjs
module.exports = {
  plugins: ["no-process-env"],
  rules: {
    "no-process-env/no-process-env": "error",
  },
  extends: ["plugin:no-process-env/legacy"],
};

The env.ts pattern

Creating a boundary around your environment configuration is a good practice. Using a validation library like Zod makes it even easier to enforce consistent types and fallbacks.

• Create an env.ts at the root of your app:

// env.ts
import { z } from "zod";

const schema = z.object({
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(["development", "test", "production"]),
  DEBUG_LOGGING_ENABLED: z
    .string()
    .default("true")
    .transform((val) => val !== "false"),
});

export const ENV = schema.parse(process.env);

• Import from env.ts elsewhere:

// db/client.ts
import { ENV } from "./env";

const client = new Client({
  connectionString: ENV.DATABASE_URL,
});

• process.env is allowed only inside env.ts / env.js; everywhere else the rule will error.

What the rule catches

• process.env.FOO
• const { env } = process;
• Bracket access: process['env']

It ignores:

• Any code inside env.ts or env.js.
• Shadowed process identifiers (e.g., function process() {}).

Options

None. The rule is purposefully minimal.

Contributing / Development

• npm run lint — lint sources and tests
• npm run test — run rule tests (Vitest + ESLint RuleTester)
• npm run build — bundle to dist/ via TSUP (ESM + d.ts)

The prepare script builds automatically on install from git, which matches npm’s publishing flow.

License

MIT