Boost your Sitecore JSS development with eslint-plugin-sitecore-jss, an ESLint plugin that enforces best practices and automates component usage checks in Sitecore projects.
Start typing to search...
When working with Sitecore JSS and XM Cloud, following best practices ensures maintainability, scalability, and proper integration with Sitecore’s editing capabilities. Sitecore provides a set of JSS components specifically designed for rendering fields such as text, rich text, images, links, and files.
Using these predefined components is recommended because:
More details can be found in Sitecore’s official documentation:
ESLint is a widely used tool for enforcing coding standards and identifying potential issues in JavaScript and TypeScript projects. It helps developers catch errors early and maintain clean, readable, and efficient code.
In the context of Sitecore JSS, manually reviewing all components for correct usage is time-consuming and error-prone. That’s where ESLint comes in! By integrating TypeScript type-checking, we can automate the process of identifying incorrect usage of Sitecore JSS components and suggest proper fixes.
To make it easier for developers to follow best practices, I’ve developed eslint-plugin-sitecore-jss, an ESLint plugin that enforces the correct usage of Sitecore JSS components in Next.js projects.
--fix .To install the plugin, run:
npm install --save-dev eslint-plugin-sitecore-jss
Or using Yarn:
yarn add -D eslint-plugin-sitecore-jss
Update your ESLint configuration (.eslintrc.json or .eslintrc.js):
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "./tsconfig.json"
},
"plugins": ["sitecore-jss"],
}
Alternatively, you can enable all rules at once with:
{
"parser": "@typescript-eslint/parser",
"parserOptions": {
"project": "./tsconfig.json"
},
"plugins": ["sitecore-jss"],
"extends": ["plugin:sitecore-jss/all"],
}
Ensures that Field<string> and TextField are wrapped with <Text>.
Incorrect:
<p>{props.fields.title.value}</p>
Correct:
<Text field={props.fields.title} tag="p" />
Ensures that RichTextField is wrapped with <RichText>.
Incorrect:
<div>{props.fields.body.value}</div>
Correct:
<RichText field={props.fields.body} tag="div" />
Ensures that ImageField is used with <Image> instead of <img>.
Incorrect:
<img src={props.fields.image.value.src} alt={props.fields.image.value.alt} />
Correct:
<Image field={props.fields.image} />
Ensures that LinkField is used with <Link> instead of <a>.
Incorrect:
<a href={props.fields.externalLink.value.href}>
{props.fields.externalLink.value.text}
</a>
Correct:
<Link field={props.fields.externalLink} />
Ensures that FileField is used with <File> instead of <a>.
Incorrect:
<a href={props.fields.file.value.src}>{props.fields.file.value.title}</a>
Correct:
<File field={props.fields.file} />
Since the initial release of eslint-plugin-sitecore-jss in beta, we've made significant improvements based on community feedback and real-world usage. Here are the key updates that make this plugin even more powerful for Sitecore JSS development:
What's New:
Why It Matters: The plugin now provides more accurate detection of Sitecore field types, reducing false positives and ensuring your TypeScript projects get the most precise linting possible.
What's New:
We've significantly enhanced the enforce-richtext-component rule to prevent a common HTML validation issue:
<p> Tag PreventionThe Issue:
Sitecore automatically wraps RichTextField content in <p> tags. When developers inadvertently use RichTextField in their own <p> tags, it creates invalid nested <p> elements:
// ❌ Creates invalid nested <p> tags
<p>{props.fields.richContent.value}</p>
// ❌ Also problematic - RichText with p tag
<RichText field={props.fields.content} tag="p" />
The Solution: The plugin now detects both scenarios and provides intelligent auto-fixes:
// ✅ Auto-fixed to valid HTML
<RichText field={props.fields.richContent} />
// ✅ Removes problematic tag attribute
<RichText field={props.fields.content} />
avoidNestedPTags: Warns when RichTextField is used inside <p> tagsavoidRichTextPTag: Warns when <RichText> component uses tag="p" attributeBoth errors include smart auto-fixes that default to using <div> wrappers, ensuring valid HTML structure.
Enhanced Error Messages: All error messages now provide clearer explanations of why certain patterns are problematic and suggest specific solutions.
Better Auto-Fixes: The auto-fix functionality has been refined to:
Through multiple patch releases (v1.1.2 - v1.1.4), we've resolved:
Update to the latest version to get all these improvements:
npm update eslint-plugin-sitecore-jss
Or install fresh:
npm install --save-dev eslint-plugin-sitecore-jss@latest
These enhancements mean:
<p> elements in your rendered pagesThis is an open-source project, and contributions are always welcome! If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request on GitHub.
🔗 GitHub Repository: eslint-plugin-sitecore-jss
It would be really helpful if you try it out in your projects and share your feedback. Let’s improve this together and make Sitecore JSS development even better! 🚀
🔗NPM: eslint-plugin-sitecore-jss
🔗GitHub: github.com/rikaweb/eslint-plugin-sitecore-jss