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

Апгрэйд кодбазы на 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 правілаў.

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