Best practices when working with JSS

Building an app compatible with Content Author management requires avoiding hard-coding component hierarchy and non-code content, such as text and images. Instead, use components from JSS packages within your components - they provide 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.

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.

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 to analyze, nurture, and personalize the website experience of the end-users. The main clients of a Sitecore site, and therefore a JSS app, are marketers, Sitecore admins, and content authors. 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.

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.

To preserve SSR compatibility, eliminate the usage of browser-specific objects, such as:

If using these browser-specific objects is necessary, wrap the code in a conditional that checks the current execution context or place the code in a lifecycle method that does not fire during SSR.

JSS has the utility function isServer() for checking whether the app is currently rendering in a Node.js context. You can use it with control flows to handle SSR context. For example:

import { isServer } from ‘@sitecore-jss/sitecore-jss’;

fetch('https://some-url', { options }).catch((error) => {
  if (isServer()) {
    // use Node's global console object to log the error
    console.error('Error:', error);
  } else {
    // Notify the user about the error. Note: this is for code demonstration only;
    // this is not an attractive way to show errors to end-users
    window.alert('An error has occurred.');
  }
});

When using third-party dependencies in your project, you might want additional configuration or middleware to support SSR.

Check the documentation for SSR compatibility - look for anything special regarding initialization options, render-time params, build configuration specific to SSR, and so on.

Common dependencies to be mindful of are:

The Import Service is used to deploy code-first Sitecore item artifacts to Sitecore, as well as for Sitecore-first developer scaffolding. This service is automatically installed when installing Sitecore Headless Services.