Галоўная / Артыкулы / Правіла Lint для React 19 у ESLint 10, калі eslint-plugin-react адаптуецца з запазджэнням

ESLint React Biome Next.js Tooling JavaScript

Правіла Lint для React 19 у ESLint 10, калі eslint-plugin-react адаптуецца з запазджэнням

Чаму eslint-plugin-react не працюе ў ESLint 10, як настройка з акцэнтам на Biome скарматоўвае праблемы з лінтаванням React да 11 правілаў, і як падключыць гэты форк да flat config і Next.js.

1826 слоў

Апгрэйд кодбазы на React да ESLint 10 часта зупіняецца чераз адну залежнасць: eslint-plugin-react. На момент напісання яго пасляпэльнай версіі не падтрымваецца ESLint 10, а выправленні ў галоўным рэпозытарыі яшчэ чакае на адключэнне. У этай статыце поясняецца прычына такой проблемы, показана, як незалежны форк @ternaus/eslint-plugin-react скорачыў набір правілаў да тых, якія ўсё ж неабходны для React 19, калі Biome ведае большую частку перагляду коду, і паказана, як ўстановіць його ў звычной конфігурацыі і ва Next.js.

Чаму правілы перагляду коду становяць большую значнасць, калі код пішаюць агенты

Чым большае колькасць заданняў команда перадае агентам-кодавальнікам, тым большае колькасць ўмов з їхніх репазітарыёў павінна быць выконвальнымі. Перагляд з боку людзяў — це дорогі спосаб разгледзець прыкметныя бяды. Функціі pre-commit hooks, тэсты, перагляд прынцыпоў структуры коду і маленькія коміты, якія можна пераглядзець, прыводзяць умовы ў форму сігналоў «працюе/не працюе», на якія можа рэагаваць агент, і дазволяюць зменшыць кожную бяду до такога розмеру, каб яе было можна діагноставаць. Linting — адны з такіх захоўніках, таму втрата слоя React lint пад час апдэйта інструментальнага комплексу — гэта не проста незгода.

Што ламаецца пад ESLint 10

Сярод значных змян у выданні ESLint 10 — адзёрванне методаў, якія давно былі занедбаны ў об’екте контэкста правіла. Найнавяцейшая выданая версія плагіна для React, eslint-plugin-react@7.37.5, паказвае ESLint 9 як высшую падтрымваную версію, а дзеякія з яго правіла ўсё ж вызываюць тыя методы. У ESLint 10 гэта прыводзіць да такога краху:

TypeError: contextOrFilename.getFilename is not a function

Метод, пра які йдзе мова, context.getFilename(), быў заменены на атрыбут context.filename у сучаснай API правіла, таму код плагіна трэба зменіць; жадных флажоў налаштавання, якія гэта б паставілі, не існуе.

Upstream стежыць за проблемай у пытанні на GitHub, засунутам 7 лютага 2026 года; кандыдатскія рашэння былі прадставлены як pull request 30 ліпеня. Ні адна з гэтых пытанняў не была закрыта да канца ліпеня 2026 года. Перад тым, як прыняць рашэнне, пераканайцеся ў іх статусе: якщо к тым часу, калі вы чытаете гэты текст, upstream уже выпусціў падтрымку ESLint 10, найпростышы спосаб можа быць апградацыя первоначальнага плагіна.

Форк, описаны тут, нацэлёваны на адзінкавую матрыцу падтрымкі:

React 19 і новэйшыя версіі
ESLint 10 і новэйшыя версіі, толькі flat config
Biome 2.5.8 і новэйшыя версіі
Node.js 22.13, 24 і 26

Настройка, якая прыпускаеся ў гэтым форку, з упорам на Biome

Выбір правіл мае сэнс толькі ў спецыфічным сераверскім середавішчы. Biome ўжо являецца галоўным форматаром і лінтэрам, які падтрымляе загальныя правілы для JavaScript, TypeScript, JSX, DOM і большасць пераканальнікаў для React. ESLint застаецца часткай інструментальнага комплексу толькі для тых функцыяй, якіх не падтрымвае Biome: плагіны для фреймворкаў і калькі правіл для React 19.

У прыкладных проектах відбуваецца:

React 19 на Next.js 16, напісаны ў TypeScript
Biome налаштаваны з прадзефініраным параметрам all
ESLint 10 з простым налаштаваннем
Yarn 4 як менеджер пакетаў
Node.js 22, 24 і 26

У такой схеме не трэба другогу, перакрываючага лінтэра. Неабходныя толькі пераканальнікі, спецыфічныя для React, якія дадаюць дапаможную інфармацыю пасля запуску Biome.

З 102 актыўных правіл на 11

Этот фарк выходзіць з репазітарыю upstream і сохраняе свою історыю Git, ліцэнзію MIT і атрыбуцыі; яго падтрымка ведаецца незалежна ад таго репазітарыю. У момент створэння галузі upstream выкарыстоўваў 104 модулі правіла. Прынацоўканне all актываўала 102 з іх (два іншыя былі знятыя з вжыцтва), а recommended паказваў 22 правілы, з якіх react/no-unsafe было явна выключана, тады засталося 21 правіла, якія ўжо дыючыя.

Пераклад усьго бы прывёў да таго, што пакет застаўся бы вялікім без чыткай мэты. У замен кожнае правіла была распакавана па типу рашэння, якое яно прыменяе:

Якщо Biome вже выдае той самы діагназ, правіла адхоўляецца.
Якщо яно стосуецца форматавання, называння, структуры файлаў аб правілаў каманды, яно належыць да Biome або да сэрвіснага канфігурацыяй прыемленае.

Якщо це шырокая гіюрістыка, якой патрабуецца доказы на рэгламентаўскай або типавой адзынце, яна адхоўвана, а не застаёцца для выдачы няпэўных рэзультатаў.

Якщо яна існуе для React 18, старых канфігурацый .eslintrc, альтернатыў парсэру чы старых API React, яна не палягае ў межах умов React 19.

Якщо яна выяўляе проблемы з правільнасцю ў React 19 чы дае корыстную павестку пра выкананне, спецыфічную для React, яна застаёцца чы ўтрымліваецца.

Рэгламенты, якія палягалі ў першай категорыі, было роўна 20, у тымчасове jsx-key, no-danger, no-unknown-property і self-closing-comp. У папцы docs форка ёсць дакумент з апраноўкамі, які супарабатоўвае кожны з іх з адпаведным рэгламентам у Biome.

Правіла, які фіксуюць стыль або палітку, напрыклад prefer-stateless-function, jsx-sort-props чырак function-component-definition, былі выключаны, адколі яны нічога не сказваюць пра правильнасць у React 19. no-unused-prop-types і no-unused-state таксама былі выключаны, таму што перагляд AST у аднам файле не можа надзяйна адпаведзіць на запытанне, якое стосуецца цэлага проекта; такія «шумныя» правіла спрабоўваюць прыучыць людзей і агентав прыменшваць значэнне рэзультатаў лінта. Усе інша, што было выключана, — это код для сумеснасці з старымі версіямі, які не палягае ў зазначанай матрыцы падтрымкі.

Толькі чатыры ID правіла з верхньага роўна пройшлі: no-deprecated, no-invalid-html-attribute, no-direct-mutation-state і jsx-no-constructed-context-values.

Новыя правіла і адна, якая была спецыяльна выключана

Тры не з’едыненыя пропозыціі з верхньага роўна былі актуальныя для пераходу на React 19:

Компаненты-флагі, які выдаюць undefined (проблема ў верхній частыні ланцуга #3020)
Забараняецца викорыстоўванне defaultProps у функцыйных компанентах (проблема #3911)
Рэкомендуецца викорыстоўванне ляжнага ініціялізатора для useState (PR #3579)

Усе тры пункты былі рэалізаваны, а пасля таго no-render-return-undefined зноў было адмовілася. React 19 дазволяе компаненту вярнуць undefined, таму заборона на гэта будзе проста схемай, маскаванай пад правіло фрэймворку. Іншыя два пункты былі реалізаваны як no-function-default-props, який пазначае API, які React 19 ігнаруе у функцыйных компанентах, а таксама як prefer-use-state-lazy-initialization — паведамленне пра непатрэбную роботу пад час кожнага рендара, напрыклад, пры викорыстоўванні expensive() заместо () => expensive().

Пяць іншых правіл спрямованы на конкрэтную працę React 19, будзь то новыя або паджорсткаваныя у поріванэнні з пакетамі вышэйшых версый: no-prop-types, no-misspelled-lifecycle-methods, jsx-no-key-after-spread, controlled-form-requires-handler і no-implicit-ref-callback-return. Правіло ref-callback ёсць гарным прыкладам таго, чаму гэта мае значэнне сёнь: адколі React 19 дазволяе функцыі-вызову ref вяртаць функцыю для чысткі, стрэловая функцыя, якая неявна ўзварабатывае значэнне з функцыі-вызову ref, больш не ёсць безнэбяжной.

Таму версія 8.0.0 мае 11 правіл, усе з яных класыфікаваныя як recommended. Дзевяць правіл на адрабоўкі ёсцю памылкамі; два правілы на выдатковасць — апавешчэннямі. Наладка all або була бы дублікатам recommended, або разлічвалася бы толькі за ступенем серьознасці, таму пакет не працюе з такой наладкай.

Калі рэальныя проекты падметлі тое, чаго не знайшлі тэсты

У версіі 8.0.0-rc.3 тэсты на адзінкавасць і пераконтроль пакетаў пройшлі. Саме пад час установкі плагіна ў рэальных прыемлячах пачаліся корыстныя аберанцы.

Першай категорыяю былі метаданы атрыбутаў HTML. Функцыя no-invalid-html-attribute адхіляла абсалютна правямыя атрыбуты, укладзіце alt, accept, name, loading, form і value для элементаў <select>, <option> і <textarea>. Ёй было дасягнуць правільнага функцыонавання пасля трох цыклів рашэння проблем і патронакоў у трэйкеры форка (#21/#22, #25/#26 і #29/#31). Пастойныя рашэнні заключаліся у тым, каб атрыбуты кантэнту HTML па стандарцу WHATWG і атрыбуты DOM у React спрэтывалі як два адналежныя источнікі інфармацыі, а не прыпускаць, што адна табеля метаданаў описвае іх оба.

Другія проблемы выйшлі з Next.js. eslint-config-next@16 стварае простую конфігурацыю, але чытае правіла з поля react.configs.recommended.rules, якое мае стары формат. Форк выклікаў толькі react.configs.flat.recommended, таму конфігурацыя зламалася ўжо перад тым, як быў працаваны хоць адны файл. У наступных змянэх (запит №24, PR №27) было дадана гэтае поле толькі для чытання, не вярнуўшы падтрымку .eslintrc. Паколькі Next.js імпортуе плагін па його неназванаму імені, таксама неабходна ўзгадка Yarn, якая паказана нижэй.

Этыя інтэграцыі стварылі кандыдатыўскія версіі 4, 5 і 6, а таксама змянілі стратэгію тэставання. Перад фінальным выпускам архіў npm практыкуецца за дапамойкай publint, імпортуецца пакетамі-корыстнікамі, напісанымі на ESM, CommonJS і TypeScript, а таксама праходзіць практыкуванне па настройкам Next.js, якія заявляецца падтрымліваючыміся пакетам, пры чым викорыстоўваецца CI на Node.js 22.13, 24 і 26. Гэты урок можна застосавіць да будзь-якага пакета з інструментамі: тэставаць трэба сам пакет, які вы выпускаеце, у тым часе як корыстнікі, якіх вы падтрымліваеце, а не толькі карэнны дрэва коду.

Рэзультатны пакет ў формате натыўнага ESM, з настройкамі толькі у формате flat-config, і сохраняе знакомы простор імен правіла react/*.

Інсталяцыя і настройка

У командах викорыстоўваецца Yarn 4. Спачатку трэба дадаць Biome, ESLint 10 і плагін як завісы развіцця:

yarn add --dev @biomejs/biome@'>=2.5.8' eslint@^10 @ternaus/eslint-plugin-react@^8.0.0

Увядзіце цэлы стабільны набор правілаў Biome і яго домэн React у файле biome.json, каб Biome пакрыў усё, што намеравана не было залучана ў форк:

{
  "linter": {
    "domains": {
      "react": "all"
    },
    "rules": {
      "preset": "all"
    }
  }
}

Потым дадзіце застаўшыяся правіла React у файл eslint.config.js. Функцыя spread з’еднае рэгістрацыю плагінамаў і правілаў з прадзефінаванага набора ў об’ект налашоўкаў, які апрануты параметрам files:

import react from '@ternaus/eslint-plugin-react';

export default [
  {
    files: ['**/*.{js,jsx,mjs,cjs,ts,tsx}'],
    ...react.configs.flat.recommended,
  },
];

Якщо параметр files уключае файлы з расшырэннямі .ts або .tsx, неабходна зарэгіструваць парсер, які падтрымлеў TypeScript, у адным з ранейшых об’ектаў налашоўкаў; прадзефінаваны набор не налаштоввае такога парсера за вас.

Запускайце гэтыя два інструменты адночасна, зазвычай як окольныя крокі CI або ў аднам скрыпце:

yarn biome check .
yarn eslint .

Ідэнтыфікаторы правілаў застаюцца з прымэткай react, таму перадзначэння, напісаныя для первасовага плагіна, будуць прыменяваны да тых правілаў, якія ўсё ще існуюць:

{
  rules: {
    'react/no-deprecated': 'error',
    'react/no-implicit-ref-callback-return': 'error',
  },
}

Інтеграцыя з Next.js

eslint-config-next імпортуе плагін пад назвай eslint-plugin-react. За дапамою Yarn можна пераказаць гэтую назву на форк пад адказ resolutions:

{
  "devDependencies": {
    "@ternaus/eslint-plugin-react": "8.0.0"
  },
  "resolutions": {
    "eslint-plugin-react": "npm:@ternaus/eslint-plugin-react@8.0.0"
  }
}

Пашанавайце два номеры версій у адпаведнасці. Адказ не дазвае eslint-config-next запускаць версію ESLint 9, яка ўжо не падтрымвана, разам з форкам для ESLint 10. Паколькі Next.js рэгіструе плагін пад назвай react, існуючыя ID правілаў react/* продовжаюць працаваць.

Калі гэты форк ўжо не падходзіць

У ём не ўключаныя всі правілы з асалоднага коду. Канфігурацыі, якія залежнаць ад react/prop-types, react/display-name чы react/jsx-sort-props, трэба прадгледзець, чы супортуюцца гэтыя правілы ў репазітарыі форка, прычым пераходзячы на яго.

Ён прыяжджае, што Biome пакрывае ўсё іншае. Без Biome чы роўнасці яму, зменшэнне да 11 правілаў заставляе ўстаць рэальныя прасочыні, такія як відсутнасць атрыбутаў key.

Ён не прысвячае ніякога кантракту сумаспадобнасці з React Native, а яго правілы DOM аналізуюць толькі элементы, якія ўтвараюць малакасовыя тэгі HTML.

Это незалежна падтрымваны форк. Спакуйце гэта з чаканнем на падтрымку ад вышэйшага проекту і перазважыце выбор, калі прыйдзе праглас з вышэйшага проекту.

Галоўныя выводы

Збой ESLint 10 выйшаў з-за адмяненняя API правіла-кантэксту, таму яго можа вылечыць толькі выпуск плагіна.
Стак, дзе Biome ў прыоритэце, патрабуе значна меншае колькасць правілаў ESLint для React; сортаванне правілаў па типе рашэння, якое яны выкарыстоўваюць, — гэта метод, які можна воспытваць для скасавання зайвых настаўленняў лінтара.
Правілы, якім патрабуецца доказ з усьго проекта, ствараюць шум у лінтары для кожнага файла і краща ўсунуць іх, чым толькі тольераваць.
Тэставанне інструментаў у тым варыянце, які бачаюць корыстувальнікі: запакаваны архіў, кожны формат модуля і рэальныя настройкі фреймворка, такія як eslint-config-next.
У Next.js алія Yarn resolutions дазволяе форку заменіць пакет без скопу, не меняючы ID правілаў.

Інформацыя пра варыянты коду і прыметкі да выданняя знаходзяцца ў рэпазітарыі форку.

Усе артыкулы Даслаць брыф