Best ESLint Setup for Sitecore XM Cloud Headless Projects

Best ESLint Setup for Sitecore XM Cloud Headless Projects

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.

Why ESLint Matters in Sitecore XM Cloud

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.

Recommended ESLint Configuration

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"
  }
}

About eslint-config-next

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-react
• eslint-plugin-react-hooks
• eslint-plugin-next

These 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.

Explanation of Key Choices

• Prettier + ESLint Integration: Automatic code formatting for clean commits.
• no-img-element disabled: We often rely on Sitecore-managed media, which may not work well with next/image.
• Strict TypeScript rules: Prevent any usage and unused variables.
• JSX quote style: prefer-double matches the format from many Sitecore HTML fields.
• Sitecore JSS linting: Directly catch and prevent misuses like not using Field, Image, or RichText helpers.

About eslint-plugin-sitecore-jss

To make ESLint even smarter for Sitecore JSS, we built the eslint-plugin-sitecore-jss.

Why This plugin?

• Warns when developers use raw JSX instead of JSS field helpers.
• Helps enforce best practices for working with Sitecore-provided content.

Installation:

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

Usage:

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.

FAQ

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.

Final Thoughts on ESLint Setup for Sitecore XM Cloud Headless Projects

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!

References

• Next.js ESLint Configuration
• eslint-plugin-sitecore-jss on npm
• Intro blog for eslint-plugin-sitecore-jss