Reading time: 3 min read
Best ESLint Setup for Sitecore XM Cloud Headless Projects
A modern and extensible ESLint configuration for Next.js-based Sitecore XM Cloud projects—complete with custom linting for JSS components.
Start typing to search...
Sitecore XM Cloud with Next.js offers powerful headless capabilities, but keeping a clean and consistent codebase across a team can be challenging. This is where ESLint comes into play. In this blog, we’ll explore a comprehensive ESLint setup optimized for Sitecore XM Cloud projects, including a powerful custom plugin you can use.
📌 This guide uses ESLint v8.x syntax and configuration.
Using ESLint ensures that your development team adheres to consistent conventions, avoids common mistakes, and improves the readability and maintainability of code—especially important when dealing with complex Sitecore JSS components and headless architecture.
Here’s a battle-tested .eslintrc.json setup ideal for a Sitecore XM Cloud + Next.js project. This configuration includes the eslint-plugin-sitecore-jss plugin by default to maximize code safety and consistency with Sitecore JSS standards:
{
"root": true,
"extends": [
"next",
"next/core-web-vitals",
"plugin:@typescript-eslint/recommended",
"plugin:sitecore-jss/all",
"prettier",
"plugin:yaml/recommended",
"plugin:prettier/recommended"
],
"plugins": ["@typescript-eslint", "prettier", "yaml", "react", "sitecore-jss"],
"ignorePatterns": [".generated/**/*", "**/*.d.ts", "**/*.js"],
"rules": {
"@next/next/no-img-element": "off",
"jsx-a11y/alt-text": ["warn", { "elements": ["img"] }],
"no-unused-vars": "off",
"@typescript-eslint/no-unused-vars": "error",
"@typescript-eslint/no-explicit-any": "error",
"jsx-quotes": ["error", "prefer-double"],
"prettier/prettier": ["error", { "endOfLine": "auto" }],
"no-html-link-for-pages": "off"
}
}
Next.js comes with built-in ESLint support. When you use "extends": ["next"], you're automatically applying a curated set of rules from the following plugins:
eslint-plugin-reacteslint-plugin-react-hookseslint-plugin-nextThese rules are maintained by the Next.js team and tailored for the App Router and core web vitals. This ESLint config takes precedence over any deprecated settings in next.config.js. You can learn more in the Next.js ESLint config documentation.
no-img-element disabled: We often rely on Sitecore-managed media, which may not work well with next/image.any usage and unused variables.prefer-double matches the format from many Sitecore HTML fields.Field, Image, or RichText helpers.To make ESLint even smarter for Sitecore JSS, we built the eslint-plugin-sitecore-jss.
npm install eslint-plugin-sitecore-jss --save-dev
Replace plugin:sitecore-jss/recommended with the more comprehensive:
"extends": ["plugin:sitecore-jss/all"]
This activates all available rules from the plugin.
You can also read our detailed introduction blog here: Improving Sitecore JSS Development with ESLint.
Q: Why is @next/next/no-img-element turned off?
A: Sitecore media fields often output URLs incompatible with next/image. Disabling this rule allows flexibility.
Q: Do I still need eslint-plugin-react?
A: Not directly—eslint-config-next already includes eslint-plugin-react. You only need to add it manually if customizing deeply.
Setting up ESLint correctly is a small step that pays off enormously in long-term project maintainability—especially in enterprise-grade platforms like Sitecore XM Cloud. By combining general best practices with Sitecore-specific linting rules via eslint-plugin-sitecore-jss, your team can write cleaner, safer, and more consistent code.
Feel free to contribute or raise issues on GitHub!