JSS development best practices

Version: 22.x

JSS applications must support use cases that regular JavaScript applications do not. Therefore, when developing JSS applications, you must follow some best practices to ensure your JSS apps deliver the functionality that is expected of them.

Avoid hard-coding layout

Building an app that is compatible with Content Author management requires that you avoid hard-coding component hierarchy and any non-code content, such as text, and images. Instead, use components from JSS packages within your components - they will hydrate your components with dynamic data generated by Content Authors.

Do not explicitly hard-code the nesting of components. Instead, use the <Placeholder> component from the JSS libraries to create a "basket" in your component that allows content authors to nest other components inside it.

Tip

Validate your application for this recommendation by checking that a Sitecore editor (such as Pages) works as expected. Content authors must be able to insert. delete, and move renderings.

Avoid hard-coding fields

If a component has values that must be controlled by Content Authors, import the associated field components from the JSS libraries, such as Text or Image, and use these components instead of those values. Never hard-code field values or inject them any other way.

Tip

Validate your application for this recommendation by checking that a Sitecore editor (such as Pages) works as expected. Content authors must be able to edit all datasource fields inline.

Inquire about authoring requirements

Sitecore is a collection of tools for building complex applications with powerful marketing features.

After a Sitecore site is built, Sitecore provides various tools and integrations to its users. As a developer, you must build JSS apps that satisfy the business requirements of these clients. This means the JSS app must remain compatible with the Sitecore authoring interface and avoid introducing technical restrictions that might limit site and content management capabilities.

Treat custom route requirements with care

In Sitecore, Content Authors have the power to control the URL of each page by organizing the content tree based on the desired URL structure. JSS apps are expected to fully support this feature. JSS apps implement custom routing to support URL structures controlled by Content Authors.

Conditionally optimize images when using the Next.js Image component

To render Sitecore image fields, we recommend that you use built-in components such as Image or Banner. JSS automatically optimizes these images for the best compatibility with Pages and Preview.

However, if you are using a custom implementation that includes the Next.js Image component instead, we recommend modifying your code to conditionally disable image optimization in edit and preview modes. The following example creates a dynamic prop named unoptimized. The value of this prop depends on the page state, so when a page is rendered in edit or preview mode, unoptimized is set to true.

RequestResponse
import { useSitecoreContext } from '@sitecore-jss/sitecore-jss-nextjs';
...
const { sitecoreContext } = useSitecoreContext();
const unoptimized = sitecoreContext.pageState !== LayoutServicePageState.Normal;

Passing the new prop into the Next.js Image component will then conditionally disable image optimization.

RequestResponse
<Image {...props} unoptimized={unoptimized}/>

Do you have some feedback for us?

If you have suggestions for improving this article,