ESLint Configuration Migrator

Overview

This package aids in the migration of the legacy ESLint configuration file format (.eslintrc.) to the new ESLint configuration file format (eslint.config.js).

Note: The generated configuration file isn't guaranteed to work in all cases, but it should get you a lot closer to a working configuration file than manually trying to migrate.

Limitations

This tool currently works well for the following config file formats:

• .eslintrc
• .eslintrc.json
• .eslintrc.yml

If you are using a JavaScript configuration file (.eslintrc.js, .eslintrc.cjs, .eslintrc.mjs), this tool currently is only capable of migrating the evaluated configuration. That means any logic you may have inside of the file will be lost. If your configuration file is mostly static, then you'll get a good result; if your configuration file is more complex (using functions, calculating paths, etc.) then this tool will not provide an equivalent configuration file.

Usage

You can run this package on the command line without installing it first by using npx or a similar tool:

npx @eslint/migrate-config .eslintrc.json
# or
bunx @eslint/migrate-config .eslintrc.json

The tool will automatically find your .eslintignore file in the same directory and migrate that into your new configuration file.

If you receive any npm errors while running using npx, install the package manually first:

npm i @eslint/migrate-config
npx @eslint/migrate-config .eslintrc.json

CommonJS Output

By default, this tool generates an ESM file (.mjs extension). If you'd like to generate a CommonJS file instead, pass the --commonjs flag:

npx @eslint/migrate-config .eslintrc.json --commonjs
# or
bunx @eslint/migrate-config .eslintrc.json --commonjs

Including a .gitignore file

If you are currently using --ignore-path .gitignore on the CLI, you'll need to read the .gitignore file into your config file. The migration can handle this for you by passing the --gitignore flag:

npx @eslint/migrate-config .eslintrc.json --gitignore
# or
bunx @eslint/migrate-config .eslintrc.json --gitignore

Targeting a specific ESLint version

By default, this tool targets the latest ESLint version available (v10). You can target v9 by passing the --target-version option:

npx @eslint/migrate-config .eslintrc.json --target-version 9
# or
bunx @eslint/migrate-config .eslintrc.json --target-version 9

Followup Steps

Once you have completed the migration, you may need to manually modify the resulting config file.

Upgrade Plugins and Double-Check Compatibility

For any plugins used in your configuration file, make sure to upgrade to the latest version. Many plugins are creating their v9-compatible versions and this tool may be out-of-date in relation to which plugins fully support v9.

After upgrading, double-check if the plugin still needs any of the compatibility utilities that were autogenerated as part of the migration.

--ext

If you are using --ext on the command line, such as:

npx eslint --ext .ts .

You'll need to remove the --ext from the command line and add an equivalent object into your configuration file. For example, --ext .ts requires an object like this in your configuration file:

export default [
    {
        files: ["**/*.ts"],
    },

    // the rest of your config
];

This tells ESLint to search for all files ending with .ts when a directory is passed on the command line. You can choose to add additional properties to this object if you'd like, but it's not required.

License

Apache 2.0

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors