📚 Add resolution steps for cyclic references when migrating from ESLint

[rakleed]

Documentation URL

https://biomejs.dev/guides/migrate-eslint-prettier/#migrate-from-eslint:~:text=Caution,such%20a%20configuration.

Description

You are saying:

Caution

Some plugins or shared configurations may export an object with a cyclic reference. Biome may fail to load such a configuration.

But what to do to resolve this?

Expectations

Provide information on what to do in this case. Or at least a link to the Issue, where you discuss how to fix this problem.

Code of Conduct

• I agree to follow Biome's Code of Conduct

[ematipico]

cc @Conaclos

[Conaclos]

I wonder if the caution is not outdated. I remember adding a function that remove cycles before converting it to JOSN.

@rakleed
Have you met any issue that could make you think it is a cyclic issue?

[rakleed]

@rakleed Have you met any issue that could make you think it is a cyclic issue?

I can wait for even a minute, but the output will be about the same and cyclic:

Small part of logs

"meta":{"type":"problem","docs":{"description":"Disallow returning a value with type any from a function","recommended":"recommended","requiresTypeChecking":true,"url":"https://typescript-eslint.io/rules/no-unsafe-return"},"messages":{"unsafeReturn":"Unsafe return of a value of type {{type}}.","unsafeReturnAssignment":"Unsafe return of type {{sender}} from function with return type {{receiver}}.","unsafeReturnThis":"Unsafe return of a value of type {{type}}. this is typed as any.\nYou can try to fix this by turning on the noImplicitThis compiler option, or adding a this parameter to the function."},"schema":[]}},"no-unsafe-type-assertion":{"defaultOptions":[],"meta":{"type":"problem","docs":{"description":"Disallow type assertions that narrow a type","requiresTypeChecking":true,"url":"https://typescript-eslint.io/rules/no-unsafe-type-assertion"},"messages":{"unsafeOfAnyTypeAssertion":"Unsafe assertion from {{type}} detected: consider using type guards or a safer assertion.","unsafeToAnyTypeAssertion":"Unsafe assertion to {{type}} detected: consider using a more specific type to ensure safety.","unsafeToUnconstrainedTypeAssertion":"Unsafe type assertion: '{{type}}' could be instantiated with an arbitrary type which could be unrelated to the original type.","unsafeTypeAssertion":"Unsafe type assertion: type '{{type}}' is more narrow than the original type.","unsafeTypeAssertionAssignableToConstraint":"Unsafe type assertion: the original type is assignable to the constraint of type '{{type}}', but '{{type}}' could be instantiated with a different subtype of its constraint."},"schema":[]}},"no-unsafe-unary-minus":{"defaultOptions":[],"meta":{"type":"problem","docs":{"description":"Require unary negation to take a number","recommended":"recommended","requiresTypeChecking":true,"url":"https://typescript-eslint.io/rules/no-unsafe-unary-minus"},"messages":{"unaryMinus":"Argument of unary negation should be assignable to number | bigint but is {{type}} instead."},"schema":[]}},"no-unused-expressions":{"defaultOptions":[{"allowShortCircuit":false,"allowTaggedTemplates":false,"allowTernary":false}],"meta":{"type":"suggestion","defaultOptions":[{"allowShortCircuit":false,"allowTaggedTemplates":false,"allowTernary":false}],"docs":{"description":"Disallow unused expressions","extendsBaseRule":true,"recommended":"recommended","url":"https://typescript-eslint.io/rules/no-unused-expressions"},"messages":{"unusedExpression":"Expected an assignment or function call and instead saw an expression."},"schema":[{"type":"object","properties":{"allowShortCircuit":{"type":"boolean"},"allowTernary":{"type":"boolean"},"allowTaggedTemplates":{"type":"boolean"},"enforceForJSX":{"type":"boolean"}},"additionalProperties":false}]}},"no-unused-vars":{"defaultOptions":[{}],"meta":{"type":"problem","docs":{"description":"Disallow unused variables","extendsBaseRule":true,"recommended":"recommended","url":"https://typescript-eslint.io/rules/no-unused-vars"},"messages":{"unusedVar":"'{{varName}}' is {{action}} but never used{{additional}}.","usedIgnoredVar":"'{{varName}}' is marked as ignored but is used{{additional}}.","usedOnlyAsType":"'{{varName}}' is {{action}} but only used as a type{{additional}}."},"schema":[{"oneOf":[{"type":"string","enum":["all","local"]},{"type":"object","additionalProperties":false,"properties":{"args":{"type":"string","description":"Whether to check all, some, or no arguments.","enum":["all","after-used","none"]},"argsIgnorePattern":{"type":"string","description":"Regular expressions of argument names to not check for usage."},"caughtErrors":{"type":"string","description":"Whether to check catch block arguments.","enum":["all","none"]},"caughtErrorsIgnorePattern":{"type":"string","description":"Regular expressions of catch block argument names to not check for usage."},"destructuredArrayIgnorePattern":{"type":"string","description":"Regular expressions of destructured array variable names to not check for usage."},"ignoreClassWithStaticInitBlock":{"type":"boolean","description":"Whether to ignore classes with at least one static initialization block."},"ignoreRestSiblings":{"type":"boolean","description":"Whether to ignore sibling properties in ... destructurings."},"reportUsedIgnorePattern":{"type":"boolean","description":"Whether to report variables that match any of the valid ignore pattern options if they have been used."},"vars":{"type":"string","description":"Whether to check all variables or only locally-declared variables.","enum":["all","local"]},"varsIgnorePattern":{"type":"string","description":"Regular expressions of variable names to not check for usage."}}}]}]}},"no-use-before-define":{"defaultOptions":[{"allowNamedExports":false,"classes":true,"enums":true,"functions":true,"ignoreTypeReferences":true,"typedefs":true,"variables":true}],"meta":{"type":"problem","docs":{"description":"Disallow the use of variables before they are defined","extendsBaseRule":true,"url":"https://typescript-eslint.io/rules/no-use-before-define"},"messages":{"noUseBeforeDefine":"'{{name}}' was used before it was defined."},"schema":[{"oneOf":[{"type":"string","enum":["nofunc"]},{"type":"object","additionalProperties":false,"properties":{"allowNamedExports":{"type":"boolean","description":"Whether to ignore named exports."},"classes":{"type":"boolean","description":"Whether to ignore references to class declarations."},"enums":{"type":"boolean","description":"Whether to check references to enums."},"functions":{"type":"boolean","description":"Whether to ignore references to function declarations."},"ignoreTypeReferences":{"type":"boolean","description":"Whether to ignore type references, such as in type annotations and assertions."},"typedefs":{"type":"boolean","description":"Whether to check references to types."},"variables":{"type":"boolean","description":"Whether to ignore references to variables."}}}]}]}},"no-useless-constructor":{"defaultOptions":[],"meta":{"type":"problem","docs":{"description":"Disallow unnecessary constructors","extendsBaseRule":true,"recommended":"strict","url":"https://typescript-eslint.io/rules/no-useless-constructor"},"hasSuggestions":true,"messages":{"noUselessConstructor":"Useless constructor.","removeConstructor":"Remove the constructor."},"schema":[]}},"no-useless-empty-export":{"defaultOptions":[],"meta":{"type":"suggestion","docs":{"description":"Disallow empty exports that don't change anything in a module file","url":"https://typescript-eslint.io/rules/no-useless-empty-export"},"fixable":"code","hasSuggestions":false,"messages":{"uselessExport":"Empty export does nothing and can be removed."},"schema":[]}},"no-var-requires":{"defaultOptions":[{"allow":[]}],"meta":{"type":"problem","deprecated":true,"docs":{"description":"Disallow require statements except in import statements","url":"https://typescript-eslint.io/rules/no-var-requires"},"messages":{"noVarReqs":"Require statement not part of import statement."},"replacedBy":["@typescript-eslint/no-require-imports"],"schema":[{"type":"object","additionalProperties":false,"properties":{"allow":{"type":"array","description":"Patterns of import paths to allow requiring from.","items":{"type":"string"}}}}]}},"no-wrapper-object-types":{"defaultOptions":[],"meta":{"type":"problem","docs":{"description":"Disallow using confusing built-in primitive class wrappers","recommended":"recommended","url":"https://typescript-eslint.io/rules/no-wrapper-object-types"},"fixable":"code","messages":{"bannedClassType":"Prefer using the primitive {{preferred}} as a type name, rather than the upper-cased {{typeName}}."},"schema":[]}},"non-nullable-type-assertion-style":{"defaultOptions":[],"meta":{"type":"suggestion","docs":{"description":"Enforce non-null assertions over explicit type assertions","recommended":"stylistic","requiresTypeChecking":true,"url":"https://typescript-eslint.io/rules/non-nullable-type-assertion-style"},"fixable":"code","messages":{"preferNonNullAssertion":"Use a ! assertion to more succinctly remove null and undefined from the type."},"schema":[]}},"only-throw-error":{"defaultOptions":[{"allow":[],"allowThrowingAny":true,"allowThrowingUnknown":true}],"meta":{"type":"problem","docs":{"description":"Disallow throwing non-Error values as exceptions","extendsBaseRule":"no-throw-literal","recommended":"recommended","requiresTypeChecking":true,"url":"https://typescript-eslint.io/rules/only-throw-error"},"messages":{"object":"Expected an error object to be thrown.","undef":"Do not throw undefined."},"schema":[{"type":"object","additionalProperties":false,"properties":{"allow":{"items":{"oneOf":[{"type":"string"},{"additionalPropertiesC

Here is my ESLint configuration:

eslint.config.js

import js from '@eslint/js';
import react from '@eslint-react/eslint-plugin';
import stylistic from '@stylistic/eslint-plugin';
import { defineConfig } from 'eslint/config';
import gitignore from 'eslint-config-flat-gitignore';
import { createOxcImportResolver } from 'eslint-import-resolver-oxc';
import checkFile from 'eslint-plugin-check-file';
import depend from 'eslint-plugin-depend';
import eslintPluginImportX from 'eslint-plugin-import-x';
import jsxA11y from 'eslint-plugin-jsx-a11y';
import noUnSanitized from 'eslint-plugin-no-unsanitized';
import packageJson from 'eslint-plugin-package-json/configs/recommended';
import reactCompiler from 'eslint-plugin-react-compiler';
import reactHooks from 'eslint-plugin-react-hooks';
import simpleImportSort from 'eslint-plugin-simple-import-sort';
import sortDestructureKeys from 'eslint-plugin-sort-destructure-keys';
import validateJsxNesting from 'eslint-plugin-validate-jsx-nesting';
import writeGoodComments from 'eslint-plugin-write-good-comments';
import globals from 'globals';
import tsEslint from 'typescript-eslint';

export default defineConfig([
  gitignore(),
  js.configs.recommended,
  eslintPluginImportX.flatConfigs.recommended,
  eslintPluginImportX.flatConfigs.warnings,
  eslintPluginImportX.flatConfigs.react,
  react.configs.recommended,
  reactHooks.configs['recommended-latest'],
  jsxA11y.flatConfigs.recommended,
  depend.configs['flat/recommended'],
  noUnSanitized.configs.recommended,
  packageJson,

  {
    files: ['**/*.js', '**/*.jsx'],
    languageOptions: {
      globals: {
        ...globals.browser,
        ...globals.es2024,
      },
      parser: tsEslint.parser,
      parserOptions: {
        ecmaFeatures: {
          jsx: true,
        },
        projectService: true,
      },
    },
    plugins: {
      'check-file': checkFile,
      'react-compiler': reactCompiler,
      'simple-import-sort': simpleImportSort,
      'sort-destructure-keys': sortDestructureKeys,
      'validate-jsx-nesting': validateJsxNesting,
      'write-good-comments': writeGoodComments,
      '@stylistic': stylistic,
      '@typescript-eslint': tsEslint.plugin,
    },
    rules: {
      'no-console': ['warn', { allow: ['error', 'warn'] }],
      'no-unused-vars': 'warn',
      'prefer-object-has-own': 'error',

      'react-hooks/exhaustive-deps': 'off',

      'jsx-a11y/no-static-element-interactions': 'off',
      'jsx-a11y/click-events-have-key-events': 'off',

      '@eslint-react/dom/no-dangerously-set-innerhtml': 'off',
      '@eslint-react/hooks-extra/no-direct-set-state-in-use-effect': 'off',
      '@eslint-react/hooks-extra/no-useless-custom-hooks': 'off',
      '@eslint-react/no-missing-key': 'off',
      '@eslint-react/web-api/no-leaked-timeout': 'off',
      '@eslint-react/hooks-extra/prefer-use-state-lazy-initialization': 'off',
      '@eslint-react/no-nested-components': 'off',
      '@eslint-react/dom/no-missing-iframe-sandbox': 'off',
      '@eslint-react/no-leaked-conditional-rendering': 'error',

      'jsx-a11y/no-autofocus': 'off',

      'simple-import-sort/imports': 'error',
      'simple-import-sort/exports': 'error',
      'import-x/first': 'error',
      'import-x/newline-after-import': 'error',

      'validate-jsx-nesting/no-invalid-jsx-nesting': 'error',

      '@typescript-eslint/no-deprecated': 'error',
    },
    settings: {
      'import-x/resolver-next': [createOxcImportResolver()],
    },
  },
  {
    files: ['src/**/*.js'],
    name: 'ban-js-file',
    rules: {
      'check-file/filename-blocklist': [
        'error',
        {
          '**/*.js': '**/*.jsx',
        },
      ],
    },
  },
  {
    files: ['*.config.js'],
    name: 'configs-of-dev-dependencies',
    rules: {
      'import-x/no-extraneous-dependencies': ['error', { devDependencies: true }],
      'import-x/no-default-export': 'off',
      'no-unused-vars': 'off',
    },
    settings: {
      'import-x/resolver': {
        node: {
          extensions: ['.js'],
        },
      },
    },
  },
]);

And only after I commented out react.configs.recommended, jsxA11y.flatConfigs.recommended, noUnSanitized.configs.recommended, '@stylistic': stylistic, '@typescript-eslint': tsEslint.plugin, the migration completed successfully in about 2 seconds.

Biome 1.9.4

[Dotify71]

Hi! I'd love to help out with this as a issue. I can add a tip to the migration guide showing users how to bypass cyclic references by temporarily commenting out complex plugins, based on the context provided above.