GitHub - JoshuaKGoldberg/eslint-plugin-erasable-syntax-only: ESLint plugin to granularly enforce TypeScript's erasableSyntaxOnly flag. ❎ (original) (raw)

ESLint plugin to granularly enforce TypeScript's erasableSyntaxOnly flag. ❎

Usage

Add this plugin to the list of plugins in your ESLint configuration file:

npm i eslint-plugin-erasable-syntax-only -D

import eslint from "@eslint/js"; import erasableSyntaxOnly from "eslint-plugin-erasable-syntax-only"; import { defineConfig } from "eslint/config";

export default defineConfig( eslint.configs.recommended, tseslint.configs.recommended, erasableSyntaxOnly.configs.recommended, // 👈 );

Rules

These are all set to "error" in the recommended config:

💡 Manually fixable by editor suggestions.

Name	Description	💡
enums	Avoid using TypeScript's enums.	💡
import-aliases	Avoid using TypeScript's import aliases.	💡
namespaces	Avoid using TypeScript's namespaces.
parameter-properties	Avoid using TypeScript's class parameter properties.

This plugin requires ESLint >=9 and Node.js >=20.18.0.

What?

eslint-plugin-erasable-syntax-only is an ESLint plugin. It provides rules that report on using syntax that will not be allowed by TypeScript's --erasableSyntaxOnly option:

Recently, Node.js 23.6 unflagged experimental support for running TypeScript files directly; however, only certain constructs are supported under this mode.

...

TypeScript 5.8 introduces the --erasableSyntaxOnly flag. When this flag is enabled, TypeScript will only allow you to use constructs that can be erased from a file, and will issue an error if it encounters any constructs that cannot be erased.

Why?

If you've already enabled TypeScript's --erasableSyntaxOnly option then you do not need this plugin.

However, if you have many existing violations, it can be time-consuming to enable TypeScript options like --erasableSyntaxOnly. TypeScript compiler options can only be configured widely at the TSConfig-level, not granularly per-file.

eslint-plugin-erasable-syntax-only allows for more gradual migrations towards only using erasable syntax. It allows you to:

Enable only one rule at a time
Restrict which rules apply to which files
Use granular ESLint eslint-disable comments instead of // @ts-expect-errors

For example, this config avoids banning enums in specific files:

import erasableSyntaxOnly from "eslint-plugin-erasable-syntax-only"; import { defineConfig } from "eslint/config";

export default defineConfig( eslint.configs.recommended, tseslint.configs.recommended, erasableSyntaxOnly.configs.recommended, // TODO (#...) { files: ["src/some/files/*.ts"], rules: { "erasable-syntax-only/enums": "off", }, }, );

Tip

Put a TODO comment linking to a tracking issue/ticket on any temporary disables of rules. It will help keep track of pending work and indicate when rule disables aren't meant to stay long-term.