eslint-plugin-erasable-syntax-only

eslint-plugin-erasable-syntax-only

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 tseslint from "typescript-eslint";

export default tseslint.config(
	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 tseslint from "typescript-eslint";

export default tseslint.config(
	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.

See Also

• @typescript-eslint/no-namespace: Dedicated, more granular typescript-eslint rule for reporting namespaces
• @typescript-eslint/parameter-properties: Dedicated, more granular typescript-eslint rule for parameter properties

Development

See .github/CONTRIBUTING.md, then .github/DEVELOPMENT.md. Thanks! 💖

Contributors

Alex Muñoz 💻

Jake Bailey 🐛

Josh Goldberg ✨ 💻 🖋 📖 🤔 🚇 🚧 📆 🔧 🐛

💝 This package was templated with create-typescript-app using the Bingo engine.

Changelog

0.3.0 (2025-03-03)

Features

• add import alias suggestions to namespaces rule (#29) (f405821), closes #21