Skip to content

Migration

ESLint deprecated their formatting rules in v8.53.0 and recommended users to migrate to ESLint Stylistic. While ESLint never removes deprecated rules, it still means that deprecated rules will not receive any future updates. In ESLint Stylistic, we already migrated all those rules and will continue to maintain them.

This guide will help you to do the migration.

ESLint Stylistic is migrated from 3 different sources packages:

  • eslint: Built-in stylistic rules for JavaScript
  • @typescript-eslint/eslint-plugin: Stylistic rules for TypeScript
  • eslint-plugin-react: Framework-agnostic JSX rules

TIP

If you are directly migrating from eslint and @typescript-eslint/eslint-plugin, we you might want to check v4 first for a even smoother migration experience.

Check the migration guide for v4

Manual Migrate

To make the rules configuration easier, we merged all three plugins into one single plugin.

sh
npm i -D @stylistic/eslint-plugin

WARNING

Since v4, we moved the plugin to ESM-only, which only supports flat config and ESLint v9+. If you are still using legacy config, please install v3.x with npm i -D @stylistic/eslint-plugin@3 first and then move to flat config.

js
import stylistic from '@stylistic/eslint-plugin'

export default [
  {
    plugins: {
      '@stylistic': stylistic
    },
    rules: {
      // ESLint built-in stylistic rules:
      // Add `@stylistic/` prefix
      'semi': 'error',
      '@stylistic/semi': 'error',

      // `@typescript-eslint` rules:
      // Change `@typescript-eslint/` to `@stylistic/` prefix
      '@typescript-eslint/semi': 'error',
      '@stylistic/semi': 'error',

      // `eslint-plugin-react` rules:
      // Change `react/` to `@stylistic/` prefix
      'react/jsx-indent': 'error',
      '@stylistic/jsx-indent': 'error',
    }
  }
]
js
// Legacy config is no longer supported in v4+
// Please use v3.x if you need to use legacy config
// We encourage you to migrate to flat config soon

// .eslintrc.js
module.exports = {
  plugins: [
    '@stylistic'
  ],
  rules: {
    // ESLint built-in stylistic rules:
    // Add `@stylistic/` prefix
    'semi': 'error',
    '@stylistic/semi': 'error',

    // `@typescript-eslint` rules:
    // Change `@typescript-eslint/` to `@stylistic/` prefix
    '@typescript-eslint/semi': 'error',
    '@stylistic/semi': 'error',

    // `eslint-plugin-react` rules:
    // Change `react/` to `@stylistic/` prefix
    'react/jsx-indent': 'error',
    '@stylistic/jsx-indent': 'error',
  }
}

And usually typescript-eslint would ask you to disable the built-in rules, in favor of the @typescript-eslint version. With ESLint Stylistic, you only need one rule to handle both JavaScript and TypeScript:

js
import stylistic from '@stylistic/eslint-plugin'

export default [
  {
    plugins: {
      '@stylistic': stylistic
    },
    rules: {
      // Previously, you need to disable the built-in rule
      'semi': 'off',
      '@typescript-eslint/semi': 'error',

      // Now only need one rule
      '@stylistic/semi': 'error',
    }
  }
]
js
// Legacy config is no longer supported in v4+
// Please use v3.x if you need to use legacy config
// We encourage you to migrate to flat config soon

// .eslintrc.js
module.exports = {
  plugins: [
    '@stylistic'
  ],
  rules: {
    // Previously, you need to disable the built-in rule
    'semi': 'off',
    '@typescript-eslint/semi': 'error',

    // Now only need one rule
    '@stylistic/semi': 'error',
  }
}

Disable Legacy Rules

In cases that you are extending some presets that still include legacy rules and haven't migrated, we provide configuration presets to disable them all.

js
// eslint.config.js
import { FlatCompat } from '@eslint/eslintrc'
import stylistic from '@stylistic/eslint-plugin'

const compat = new FlatCompat()

export default [
  // `extends` is not supported in flat config, can you use `@eslint/eslintrc` to handle it
  ...compat({
     extends: [
      'eslint:recommended',
      'plugin:@typescript-eslint/recommended',
      // ...
    ],
  }),
  // override the legacy rules
  stylistic.configs['disable-legacy'],
  // your own rules
  {
    plugins: {
      stylistic,
    },
    rules: {
      'stylistic/semi': 'error',
      // ...
    }
  }
]
js
// Legacy config is no longer supported in v4+
// Please use v3.x if you need to use legacy config
// We encourage you to migrate to flat config soon

// .eslintrc.js
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    // ...
    'plugin:@stylistic/disable-legacy',
  ],
  plugins: [
    '@stylistic'
  ],
  rules: {
    '@stylistic/semi': 'error',
    // ...
  }
}

Packages Metadata

If you want to handle the migration on your own, we also expose the metadata for easier programmatic usage.

sh
npm i -D @eslint-stylistic/metadata
js
import { rules, packages } from '@eslint-stylistic/metadata'

console.log(rules)

Released under the MIT License.