ESLint Rules for TypeScript Enums

2.1.0 · active · verified Sun Apr 19

eslint-plugin-typescript-enum provides ESLint rules specifically designed to manage and disallow the use of TypeScript enums within a project. The plugin operates on the premise that TypeScript enums, while a core language feature, introduce runtime representations that conflict with TypeScript's design goal of being a typed superset of JavaScript without adding runtime functionality. It highlights concerns such as potential type unsafety, caveats, and better modern alternatives like `const assertions`, `string unions`, and `discriminated unions`. The current stable version is 2.1.0, and the package appears to have an active release cadence, with several minor versions released recently. Its key differentiator is its explicit stance against TypeScript enums, aligning with a growing sentiment in the TypeScript community that discourages their use in favor of more JavaScript-native patterns. This makes it a critical tool for developers aiming to maintain a consistent, future-proof, and JavaScript-aligned codebase by enforcing alternatives.

Common errors

```
Parsing error: 'enum' keyword cannot be used.
```
cause The ESLint parser is not correctly configured for TypeScript or is missing `@typescript-eslint/parser`.

fix Ensure `parser: "@typescript-eslint/parser"` is set in your `.eslintrc.js` and that `@typescript-eslint/parser` is installed as a dev dependency.
```
Error: Failed to load parser '@typescript-eslint/parser' declared in '.eslintrc.js'.
```
cause The `@typescript-eslint/parser` package is not installed or ESLint cannot find it in your project's `node_modules`.

fix Run `npm install --save-dev @typescript-eslint/parser` or `yarn add -D @typescript-eslint/parser` to install the parser.
```
ESLint: 'Do not use TypeScript enums. Consider using union types, 'as const' objects, or discriminated unions instead.' (typescript-enum/no-enums)
```
cause An enum declaration was found in your TypeScript code, and the `typescript-enum/no-enums` rule is enabled (e.g., via the recommended config).

fix Refactor the enum to use an alternative like a string union type (`type Status = 'active' | 'inactive';`), an `as const` object (`const Status = { ACTIVE: 'active' } as const;`), or a discriminated union.

Warnings

breaking Enabling the `plugin:typescript-enum/recommended` configuration will disallow all uses of TypeScript enums. This is a breaking change for existing codebases that utilize enums and will result in ESLint errors until they are refactored.
Fix: Refactor existing TypeScript enums to use modern alternatives such as `const assertions`, `string unions`, or `discriminated unions` before enabling the recommended configuration.
gotcha TypeScript enums have runtime representations and are not erased from emitted JavaScript, which conflicts with TypeScript's design non-goal of not providing additional runtime functionality. This can lead to unexpected bundle sizes or runtime behavior.
Fix: Favor `const assertions` on objects (`as const`) or `string unions` for type-safe constant sets, which are entirely compile-time constructs.
gotcha Using `const` enums with `@babel/plugin-transform-typescript` is problematic because `const` enums require type information to compile. Babel's TypeScript transform operates without type information.
Fix: Avoid `const` enums when using Babel for TypeScript transformation. Instead, use literal types or `as const` objects that do not require type-aware transformations.
gotcha TypeScript enums can have caveats and edge cases, with some aspects even considered not type-safe, leading to unexpected behavior at runtime or compile-time.
Fix: Review articles on TypeScript enum alternatives (e.g., `2ality.com/2020/02/enum-alternatives-typescript.html`) to understand safer and more robust patterns.

Install

npm install eslint-plugin-typescript-enum npm
yarn add eslint-plugin-typescript-enum yarn
pnpm add eslint-plugin-typescript-enum pnpm

Imports

ESLint plugin configuration
wrong:
```
plugins: ["eslint-plugin-typescript-enum"]
```
correct:
```
plugins: ["typescript-enum"]
```
When configuring ESLint, use the short plugin name 'typescript-enum' without the 'eslint-plugin-' prefix.
Recommended rule set
wrong:
```
extends: ["typescript-enum/recommended"]
```
correct:
```
extends: ["plugin:typescript-enum/recommended"]
```
The 'recommended' configuration path requires the 'plugin:' prefix.
TypeScript parser for ESLint
wrong:
```
parser: "babel-eslint"
```
correct:
```
parser: "@typescript-eslint/parser"
```
This plugin requires `@typescript-eslint/parser` to correctly analyze TypeScript code. Other parsers for JavaScript or Babel may not provide the necessary type information or AST structure.

Quickstart

Configures ESLint to use the recommended rules of `eslint-plugin-typescript-enum`, effectively disallowing TypeScript enums in your project by applying the recommended rule set.

module.exports = {
  // Specifies the ESLint parser for TypeScript
  parser: "@typescript-eslint/parser",
  // Specifies the ESLint plugin to use
  plugins: ["typescript-enum"],
  // Extends with the recommended configuration from the plugin, disallowing enums
  extends: ["plugin:typescript-enum/recommended"],
  // Optional: Add other ESLint configurations as needed
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: "module",
    // Required for rules that need type information
    project: './tsconfig.json'
  },
  rules: {
    // Additional custom rules or overrides if necessary
  }
};

view raw JSON →