Reading time: 13 min read

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.

Portrait photo of Sohrab Saboori, article author

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.

Before:

<h1 className="title">{props.fields.title.value}</h1>
<p>{props.fields.subtitle?.value}</p>
<img src={props.fields.image.value!.src} alt="Hero" loading="lazy" />
<div dangerouslySetInnerHTML={{ __html: props.fields.body.value ?? "" }} />
<a href={props.fields.link.value?.href}><span>Read more</span></a>

After eslint --fix:

<Text field={props.fields.title} tag="h1" className="title" />
<Text field={props.fields.subtitle} tag="p" />
<Image field={props.fields.image} alt="Hero" loading="lazy" />
<RichText field={props.fields.body} tag="div" />
<Link field={props.fields.link}><span>Read more</span></Link>

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:

npm install --save-dev eslint-plugin-sitecore-jss @typescript-eslint/parser 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:

import tsParser from "@typescript-eslint/parser";
import sitecoreJss from "eslint-plugin-sitecore-jss";
export default [
  {
    files: ["**/*.{ts,tsx}"],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  },
  ...sitecoreJss.configs["flat/recommended"],
];

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.

ConfigRulesSeverity
flat/recommendedthe five component ruleswarn
flat/strictthe five component ruleserror
flat/allalias of flat/recommendedwarn

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:

module.exports = {
  overrides: [
    {
      files: ["*.tsx"],
      parser: "@typescript-eslint/parser",
      parserOptions: {
        project: "./tsconfig.json",
        tsconfigRootDir: __dirname,
      },
      extends: ["plugin:sitecore-jss/recommended"],
    },
  ],
};

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:

rules: {
  "sitecore-jss/enforce-text-component": "error",
  "sitecore-jss/enforce-richtext-component": "error",
  "sitecore-jss/enforce-image-component": "warn",
  "sitecore-jss/enforce-link-component": ["warn", { importSource: "@sitecore-jss/sitecore-jss-react" }],
  "sitecore-jss/enforce-file-component": "warn",
}

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:

// before
import { Field, ImageField } from "@sitecore-content-sdk/nextjs";
<h1 className="title">{fields.Title.value}</h1>
<img src={fields.Image.value?.src} alt="Hero" className="hero" />
// after `eslint --fix`
import { Field, ImageField, Text, Image } from "@sitecore-content-sdk/nextjs";
<Text field={fields.Title} tag="h1" className="title" />
<Image field={fields.Image} alt="Hero" className="hero" />

When a problem is reported without a fix

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.

<Typography>{props.fields.title.value}</Typography>

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 href={props.fields.link.value.href}>{props.fields.title.value}</a>

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.

<div dangerouslySetInnerHTML={{ __html: props.fields.body.value || "<p>Default</p>" }} />

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:

import NextLink from "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:

npm install --save-dev eslint-plugin-sitecore-jss@latest

2. Choose the config format

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.

Sources

  1. Improving Sitecore JSS Development with ESLint: Introducing eslint-plugin-sitecore-jss — Fishtank
  2. ESLint v9.0.0 released — ESLint Blog
  3. Migrate to v10.x — ESLint Documentation
  4. Upgrade JSS 22.0 Next.js apps to Content SDK 2.1 — Sitecore Documentation
  5. Upgrade JSS Next.js apps to Content SDK — Sitecore Documentation
  6. @typescript-eslint/parser — typescript-eslint Documentation
  7. Linting with Type Information — typescript-eslint Documentation
  8. use client — Next.js Documentation
  9. Generating provenance statements — npm Docs
  10. eslint-plugin-sitecore-jss — npm
  11. rikaweb/eslint-plugin-sitecore-jss — GitHub (README, changelog, rule documentation)