Goals

1. Enable no-undeclared-env-vars rule to check custom environment variable objects (e.g. env)
2. Prevent environment variables that are not accounted for in turbo.json from silently bypassing the rule when using a custom environment variable object

Background

There is a somewhat common pattern in TypeScript codebases of validating environment variables with zod, like this:

import {z} from 'zod';

const envSchema = z.object({
  API_URL: z.string().url(),
});

export const env = envSchema.parse(process.env);

By using the env object instead of process.env, you get type-safety, editor auto-complete and implicitly ensure the runtime validation happens before any environment variable is being accessed.

However, this pattern isn’t currently compatible with the no-undeclared-env-vars rule in eslint-plugin-turbo, since it only checks direct usage of process.env and import.meta.env. As a result, references like env.API_URL won’t trigger a linting error if API_URL is not listed in turbo.json.

There are workarounds, but they’re either verbose or weaken the validation guarantees this pattern provides:

1. Adding a global type enhancement for process.env with the type inferred from the zod schema instead of using the exported env object. This makes it harder to guarantee the validation runs before an environment variable is being accessed, since you now have to manually ensure the zod parsing is the very first thing that happens when the app is started
2. Creating a new object that maps each environment variable in process.env to itself, introducing a usage of process.env.{ENV_VAR} that the ESLint plugin can check, and parsing that object instead of process.env. This is just a lot more verbose, especially when the app uses a lot of environment variables.

Proposal

Add a setting to the no-undeclared-env-vars rule that allows users to specify the name(s) of custom environment variable objects and check them in addition to or instead of process.env and import.meta.env.

'rules': {
  'turbo/no-undeclared-env-vars': [
    'error',
    {
      envObjectName: 'env',
    },
  ],
},

Other tools, like Drizzle's ESLint plugin, do something similar by letting users define the name of the Drizzle object used in their codebase to check method calls on this object.

Happy to help contribute if this sounds like something worth adding to the project!