eslint-plugin-sitecore-jss 2.0: ESLint 9 and 10 flat config, Content SDK support, and a safer auto-fix
Version 2.0.0 of eslint-plugin-sitecore-jss runs on ESLint 9 and 10 with flat config, recognises Sitecore Content SDK field types next to JSS, and only rewrites code when the fix cannot lose anything. Here is what changed, how to set it up, and how to move from 1.x.
Sohrab is a senior front-end developer specializing in React, Next.js, and Sitecore Headless—building lightning-fast, scalable, and seamless digital experiences.
The toolchain moved, so the plugin had to
In March 2025 I introduced eslint-plugin-sitecore-jss in Improving Sitecore JSS Development with ESLint[1]. The idea has not changed: when a component reads a Sitecore field's value by hand and prints it in a plain HTML element, the page still renders, but the field is no longer editable in Sitecore Pages, and the media handling, link resolution and rich text rendering of the Sitecore field components are skipped. The plugin finds those places through the TypeScript type checker and rewrites them to <Text>, <RichText>, <Image>, <Link> and <File>.
That post covered the beta through 1.1.5, and all of its setup was written for .eslintrc and JSS. Both have moved since. Version 2.0.0 is a rewrite for the current toolchain: ESLint 9 and 10 with flat config, typescript-eslint 8, and the Sitecore Content SDK next to JSS. The rule names and the recommended and all configs are the same, so this post only covers what is different: why a major version was needed, what the rules now catch, how to configure it, how the auto-fix decides what it may rewrite, and how to migrate from 1.x.
Why a version 2
ESLint changed its configuration format. ESLint 9 made flat config (eslint.config.js) the default and deprecated .eslintrc[2]. ESLint 10 no longer supports the old format at all, and it removed rule-context methods such as context.getSourceCode() in favour of context.sourceCode[3]. The 1.x line only documented .eslintrc. Version 2.0.0 ships flat configs, keeps the legacy ones for ESLint 8.57, and its rules use the APIs ESLint 10 requires.
Sitecore front ends are moving to the Content SDK. Sitecore describes the Content SDK as a major upgrade from JSS for SitecoreAI (the product formerly named XM Cloud) [4], and its upgrade guide replaces @sitecore-jss/sitecore-jss-nextjs with @sitecore-content-sdk/nextjs[5]. The field types and field components keep their names, so the same mistakes are possible in a Content SDK app. Version 2.0.0 recognises the field types from both package families.
The 1.x auto-fix was not safe enough to run unattended. It could drop text that sat next to the field, it turned a component wrapper into <Text tag="Typography">, it missed fields read through optional chaining, and it left the import of the new component to you. When type information was missing, the rules did nothing and said nothing. Fixing these changes what the rules report, which is the second reason for a major version.
What is new in 2.0.0
Flat configs for ESLint 9 and 10: flat/recommended, flat/strict, flat/all
Legacy configs still work on ESLint 8.57, with a new strict config
Content SDK field types are recognised next to JSS
Optional chaining, non-null assertions and type assertions are detected
dangerouslySetInnerHTML with a rich text field is reported and fixed
The fix adds the missing import, with an importSource option
Unsafe rewrites are reported without a fix
A test suite, a CI matrix and npm provenance for releases
More ways of reading a field are detected
A field read through optional chaining, a non-null assertion or a type assertion is now found, and the fix points at the field itself, never at the asserted value. enforce-richtext-component also reports a rich text field that is injected with dangerouslySetInnerHTML, including the ?? "" and || "" variants, and a text field rendered without .value is reported too.
The nested paragraph checks from 1.1.5 are still there: a rich text field inside <p>, or <RichText tag="p">, is fixed to a <RichText> without a tag, and tag={"p"} is now handled like tag="p".
Some elements are left alone on purpose. <title>, <option>, <textarea>, <script> and <style> can only hold plain text, so reading .value inside them is correct and is never reported.
Content SDK and JSS in the same rules
The rules decide by type, not by variable name or import path. A Field<string>, RichTextField, ImageField, LinkField or FileField is recognised whether it is declared by @sitecore-jss/sitecore-jss-nextjs, @sitecore-jss/sitecore-jss-react, @sitecore-content-sdk/nextjs or @sitecore-content-sdk/react. A project that is halfway through a JSS to Content SDK migration can keep one lint configuration for both.
Setting up flat config
Install the plugin together with the parser and TypeScript:
The supported ranges are ESLint 8.57, 9 or 10, @typescript-eslint/parser 7 or 8, TypeScript 4.8.4 up to 6.0, and Node.js 18.18 or newer. ESLint 10 itself needs Node.js 20.19 or newer [3].
Then add the parser block and one of the plugin's configs to eslint.config.mjs:
If the project already uses the typescript-eslint package with tseslint.config(...) or defineConfig(...), spread sitecoreJss.configs["flat/recommended"] into that array instead. An app that gets its parser through eslint-config-next should still list @typescript-eslint/parser as a direct dev dependency, because the config file now imports it.
Config
Rules
Severity
flat/recommended
the five component rules
warn
flat/strict
the five component rules
error
flat/all
alias of flat/recommended
warn
The rules need type information. They read the TypeScript types of your fields, so parserOptions.projectService (or the older parserOptions.project) must be set. typescript-eslint recommends projectService[6][7]. In 1.x a missing setting meant the rules silently did nothing; in 2.0.0 ESLint stops with the standard typescript-eslint configuration error.
The flat configs only apply to .tsx files. They are scoped to **/*.tsx. The rules look at JSX, which TypeScript only allows in .tsx files, so nothing is missed, and eslint . does not fail on eslint.config.mjs, next.config.js, vitest.config.mts and other files that are parsed without type information. To lint type-checked .jsx files as well, enable the rules for them individually.
Legacy config on ESLint 8
.eslintrc keeps working on ESLint 8.57. Put the parser settings and the plugin config in an overrides entry for *.tsx:
plugin:sitecore-jss/all (the same as recommended) and plugin:sitecore-jss/strict exist too. Use a .cjs file rather than JSON so that tsconfigRootDir can be an absolute path. Keep the block inside overrides: the legacy configs have no file scope of their own, and at the top level the rules would also run on .js files, which have no type information.
Rules and the importSource option
The five rules can also be enabled one by one, and each accepts one option object:
importSource is the package a component is imported from when the file has no Sitecore import that can be extended. Without it, the plugin uses the package family that declares the field's type, and falls back to @sitecore-jss/sitecore-jss-nextjs. A component that is already imported from the importSource package is recognised as the Sitecore component.
How the auto-fix behaves
The fixer in 2.0.0 follows one rule: a fix is only offered when it cannot lose code or shadow another binding. Everything else is still reported, so nothing is hidden, but you make the change yourself.
Attributes are kept. Every attribute and spread on the element stays (className, id, data-*, {...rest}). Only the attribute that the component derives from the field is dropped: src on <img>, href on <a>, and dangerouslySetInnerHTML.
Children of a link are kept. An <a> becomes <Link field={…}>children</Link> or <File field={…}>children</File>. The children are removed only when they do nothing but re-render the field's own text, such as {link.value.text} or the file's title or displayName, which the component renders by itself. When the only child of the anchor is a different text field, the anchor still becomes <Link> or <File> and that text field is reported separately (see below); it is never rewritten to <Text tag="a">.
The import is added. When the component is not imported yet, a second problem, missingImport, is reported next to the first element that needs it. Its fix extends an existing import from a Sitecore package, or adds a new import after the last one. The package comes from the importSource option, then from an existing Sitecore import in the file, then from the package that declares the field's type. In a file that has no imports and starts with "use client", the new import goes after the directive, because the directive has to stay above any imports [8].
In a Content SDK component the result looks like this:
There are five situations in which the rule reports the misuse and leaves the code alone.
Other children sit next to the field.<Text> replaces the whole element, so the surrounding text would be lost. Move the text out, or give it its own element. The same applies to a field that sits next to an HTML entity such as a non-breaking space.
<h3>Hello {props.fields.title.value}</h3>
The wrapper is a component, not an HTML element. The plugin cannot know what Typography renders, so it reports a dedicated message (useTextComponentInWrapper or useRichTextComponentInWrapper) that suggests passing the field to <Text> inside the wrapper, or letting the component accept the field.
The element is a link that renders a text field. The link rule rewrites the anchor to <Link> (or <File> for a file field) and keeps the child. The text rule then reports the text field inside it with useTextComponentInWrapper and leaves it for you to wrap in <Text>.
A dangerouslySetInnerHTML value has a non-empty fallback. The fix is offered when the fallback is empty (?? "", || ""). <RichText> cannot reproduce any other fallback, so the element is reported only.
The component name is already taken. This is the common case in Next.js apps: the file imports Link from next/link or Image from next/image, has a local or type-only binding with the same name, or uses the DOM global of that name (new Image(), a parameter typed File). Adding a Sitecore import of the same name would break the file, so the raw <a> or <img> is reported only. Alias one of the two imports and run --fix again:
importNextLinkfrom"next/link";
A note on parserOptions.project
With the classic parserOptions.project, ESLint's later fix passes lint the rewritten text against stale type information. A --fix run can then report zero remaining problems even though unfixable ones exist; a second plain eslint run shows them. The fixes themselves are applied correctly in both modes. With projectService the first run already reports them.
Migrating from 1.x
Most 1.x setups only need the dependency update, because the rule names and the recommended and all configs are unchanged.
1. Update the toolchain
ESLint 8.0 to 8.56, typescript-eslint 5 and 6, and Node.js 14 and 16 are no longer supported. Move to ESLint 8.57 or newer and @typescript-eslint/parser 7 or 8, then update the plugin:
On ESLint 9 or 10, use the flat config shown above. On ESLint 8.57, the existing .eslintrc with extends: ["plugin:sitecore-jss/recommended"] or plugin:sitecore-jss/all keeps working. Move the parser, parserOptions.project and the extends into an overrides entry for *.tsx, as shown above: the rules now need type information, which .js files linted by the same config do not have.
3. Replace enforce-all-components
enforce-all-components still works but is deprecated. If you enabled it directly, switch to a config or to the five individual rules. The all config now enables the five rules instead of the meta-rule, at the same severity, so findings carry the individual rule ids; an eslint-disable comment that names sitecore-jss/enforce-all-components has to name the specific rule instead.
4. Make sure type information is configured
If 1.x was quiet in your project, check that this was not because type information was missing. Version 2.0.0 fails with a configuration error in that case. Prefer parserOptions.projectService over parserOptions.project.
5. Run the linter and review what is left
Expect more findings than before: optional chaining is detected, the import is reported and added, and dangerouslySetInnerHTML is covered. Expect fewer rewrites that need repair afterwards. Run eslint --fix, then a plain eslint, and handle what remains by hand: elements with mixed children, component wrappers, links that wrap a text field, and files where Link or Image already comes from Next.js.
Other changes to know about
Message texts were rewritten, and there are new message ids (missingImport, useTextComponentInWrapper, useRichTextComponentInWrapper, avoidDangerouslySetInnerHTML), which matters only if you assert on them in your own tooling. The plugin no longer writes console.warn output for ordinary <a> and <img> elements. @typescript-eslint/utils is now a runtime dependency of the plugin, so it no longer depends on hoisting in your node_modules.
How it was tested
The 1.x line had no automated tests. Version 2.0.0 has a rule test suite built on vitest and @typescript-eslint/rule-tester, with type-only fixture packages for JSS and the Content SDK, an end-to-end test that runs the real ESLint CLI, and a CI matrix on Node.js 20 and 22 with ESLint 8.57, 9 and 10. Releases are published with npm provenance, a signed statement that links the package to its source and build [9].
Before the release I also ran the packed plugin against a Content SDK starter kit, on an App Router app and a Pages Router app (Content SDK 1.4.1, Next.js 15, ESLint 9, flat config with projectService), and on a third app with Content SDK 2.3 and Next.js 16.
No false positives. The starters' own components, 93 files in the two main apps, produced zero findings. Code that looks close to a violation was correctly left alone: .value used as a condition, a link text with a fallback inside a Sitecore Link, a derived value in <title>, and an <img> whose src is a plain string.
Every planted mistake was found. A set of deliberately wrong components produced 26 findings per app. eslint --fix resolved 22 of them, including the imports, and the remaining 4 were exactly the report-only cases described above. The fixed files passed tsc --noEmit and next build in both apps.
A code review before the release turned up further edge cases; its blocking and should-fix items were fixed before publishing.
The starters all use ESLint 9, so the legacy .eslintrc path was not exercised on a real app; it is covered by the plugin's own ESLint 8.57 integration test.
Known limits
A field value that reaches the JSX through a local variable is not traced.
Field<number> is not covered in 2.0.
When a multi-line import is extended, the new names are appended to its last line; a formatter such as Prettier tidies that up.
Try it
Version 2.0.0 is published as eslint-plugin-sitecore-jss on npm. The source, the changelog with the full list of changes, the v2.0.0 release, and a documentation page per rule in docs/rules are in the GitHub repository. Issues and pull requests are welcome there, especially false positives and patterns from real projects that the rules miss.