Why Using Sitecore JSS Components is Best Practice
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:
- They ensure compatibility with Sitecore Experience Editor.
- They handle field-specific rendering correctly.
- They improve consistency across your Next.js project.
More details can be found in Sitecore’s official documentation:
- Sitecore JSS Components Documentation.
- For a deeper dive into how different Sitecore JSS field types work and how to use them correctly, check out All Sitecore JSS Types and How to Use Them.
The Role of ESLint in JavaScript Code Quality
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.
Introducing ESLint Plugin for Sitecore JSS
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.
Features
- Detects incorrect usage of Sitecore JSS components.
- Recommends proper Sitecore JSS components for fields.
- Supports auto-fixing with
--fix. - Integrates seamlessly with TypeScript and ESLint.
- Includes multiple individual rules, or a single rule for all components.
Installation
To install the plugin, run:
npm install --save-dev eslint-plugin-sitecore-jss
Or using Yarn:
yarn add -D eslint-plugin-sitecore-jss
Usage
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"],
}
Rules and Examples
enforce-text-component
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" />
enforce-richtext-component
Ensures that RichTextField is wrapped with <RichText>.
Incorrect:
<div>{props.fields.body.value}</div>
Correct:
<RichText field={props.fields.body} tag="div" />
enforce-image-component
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} />
enforce-link-component
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} />
enforce-file-component
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} />
Update: Major Enhancements Since Beta Release
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:
Enhanced TypeScript Support (v1.1.0)
What's New:
- Full TypeScript migration for all rule implementations
- Improved type checking utilities for better field type detection
- Enhanced support for complex type scenarios including union and intersection types
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.
Advanced RichText Component Protection (v1.1.5)
What's New:
We've significantly enhanced the enforce-richtext-component rule to prevent a common HTML validation issue:
Problem Solved: Nested <p> Tag Prevention
The 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} />
New Error Messages
avoidNestedPTags: Warns when RichTextField is used inside<p>tagsavoidRichTextPTag: Warns when<RichText>component usestag="p"attribute
Both errors include smart auto-fixes that default to using <div> wrappers, ensuring valid HTML structure.
Improved Developer Experience
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:
- Choose appropriate wrapper elements based on context
- Preserve existing field references accurately
- Maintain code formatting and structure
Production-Ready Stability
Through multiple patch releases (v1.1.2 - v1.1.4), we've resolved:
- Build process improvements
- TypeScript compilation edge cases
- Enhanced error handling in type checking utilities
Getting the Latest Version
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
Impact on Your Development Workflow
These enhancements mean:
- Cleaner HTML Output: No more invalid nested
<p>elements in your rendered pages - Enhanced Accessibility: Screen readers and assistive technologies work better with proper HTML structure
- Faster Development: Auto-fixes handle common mistakes automatically
Contribute and Provide Feedback!
This 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
References:
