eslint-plugin-env-compose

ESLint plugin for compose-env that catches typos and unknown key access on config objects at lint time.

Installation

npm install --save-dev eslint-plugin-env-compose

ESLint 8 or 9 must also be installed.

Setup (ESLint 9 flat config)

// eslint.config.js
import envCompose from 'eslint-plugin-env-compose'

export default [
  ...envCompose.configs.recommended,
]

The recommended config enables the no-unknown-key rule as a warning on all files.

Rules

env-compose/no-unknown-key

Disallows accessing keys on compose-env config objects that are not defined in the schema. Catches typos like config.DATABSE_URL before they reach runtime.

// ❌ error: 'DATABSE_URL' is not defined in the env-compose schema
const url = config.DATABSE_URL

// ✅ ok
const url = config.DATABASE_URL

The rule checks both dot notation (config.KEY) and bracket notation (config['KEY']).

Configuring Known Keys

You must tell the rule which keys are valid. There are three ways to do this.

Option 1: Inline key list

// eslint.config.js
import envCompose from 'eslint-plugin-env-compose'

export default [
  ...envCompose.configs.recommended,
  {
    rules: {
      'env-compose/no-unknown-key': ['error', {
        keys: ['PORT', 'DATABASE_URL', 'API_KEY', 'NODE_ENV'],
      }],
    },
  },
]

Option 2: Schema file (JSON)

Point the rule to a JSON file that describes your schema. Two formats are supported:

Format 1 — explicit key list:

{
  "keys": ["PORT", "DATABASE_URL", "API_KEY"]
}

Format 2 — schema object (keys are read from the top level):

{
  "PORT":         { "type": "port" },
  "DATABASE_URL": { "type": "url"  },
  "API_KEY":      { "type": "string" }
}

// eslint.config.js
export default [
  ...envCompose.configs.recommended,
  {
    rules: {
      'env-compose/no-unknown-key': ['error', {
        schemaFile: './src/config.schema.json',
      }],
    },
  },
]

Option 3: Custom config variable names

By default the rule checks variables named config. If your config object has a different name, set configVariables:

{
  rules: {
    'env-compose/no-unknown-key': ['error', {
      configVariables: ['appConfig', 'cfg'],
      keys: ['PORT', 'DATABASE_URL'],
    }],
  },
}

Rule Options Reference

| Option | Type | Default | Description | |-------------------|------------|----------------|----------------------------------------------------------------------------------------------------------------| | keys | string[] | — | Explicit list of valid key names. Takes precedence over schemaFile. | | schemaFile | string | — | Path to a JSON schema file. Supports { keys: [...] } or a schema object where top-level keys are the names. | | configVariables | string[] | ['config'] | Variable names to treat as compose-env config objects. |

ESLint 8 (legacy config)

// .eslintrc.js
module.exports = {
  plugins: ['env-compose'],
  rules: {
    'env-compose/no-unknown-key': ['warn', {
      keys: ['PORT', 'DATABASE_URL'],
    }],
  },
}