That subtitle might be slightly triggering for some but actually you can use the fact that Sitecore JSS is not truly headless to your advantage. If you work on a Sitecore project, why not use the power of the beast that adds a fancy content editing experience, personalization, localization and much more?

EDIT (asked for by Sitecore, March 10th, 2020): It seems that the word headless is slowly changing its meaning now that the big CMS Vendors are stepping into the game. It’s clear that JSS has a tight coupling to Sitecore concepts like placeholders, renderings, content types and static UUID’s. You can however build the front-end the way you want it. You can still deploy the front-end separately from the back-end. If you use Contentful (or a similar system) you also have to follow their data modeling, you can’t just replace the CMS without consequences. Now what defines headless exactly? I’d say that you can separately deploy the front-end from the back-end. I’m ready for the flame war with the keyboard warriors now. Luckily I don’t have comments on my JAMstack website :)

When you are doing things “code first” it means that the front-end developer decides on how the Sitecore system works with the components and the data model. Make sure you actually understand the Sitecore basics before even trying this. All is fun and games in “disconnected” mode until you connect and try to edit content. In my experience (even knowing Sitecore) it is a pretty bad time if you haven’t followed the basic rules of Sitecore.

This post outlines a couple of best practices you should follow to have less issues when going from standalone or (disconnected mode) to the integrated mode with the Sitecore Experience Editor.

TL;DR follow the Sitecore way. Do not think it is truly headless and that you can just build whatever you want as a front-end developer. Make sure your components work in Sitecore’s multiple modes: Experience Editor mode, Server side rendered mode, Single page app mode.

Best practice 1: code defensively.

When you add a component onto the page in Experience Editor all field values are null or undefined. Wrap all fields in “if” statements to make sure you don’t get the famous null reference exception.

Best practice 2: Use the JSS front-end components.

To be able to edit elements properly or to use localization in a smooth way, always use the native components JSS gives you for links, images, texts, rich text fields, etc. If you make your own components that just read the data model as properties, the presentation works but the content editing experience is less than ideal. You can’t inline edit the text in a graphical way for example, and you have to reload the Experience Editor window after a change. Knowing how slow the Experience Editor actually is, this is very painful.

Best practice 3: Take SSR into account.

Both Experience Editor and the normal presentation of your app have a Server Side rendering component. Make sure to add “if” statements around all browser API related code. If you don’t do that, SSR will not be able to render your app. This either happens silently and SSR just doesn’t happen or it can cause issues when you are in Experience Editor mode. The JavaScript of the Experience Editor generally just gives you and “Unexpected Error”. Quick tip: first always check for SSR issues in your code or in the third party library you might be using as a dependency if an “Unexpected Error” happens in Experience Editor. This fixes 95% of the problems you see.

Best practices 4: Make specific choices for Experience Editor mode of your component.

The Experience Editor is a special sort of beast. In my personal opinion it has a lot of flaws and I don’t like to use it. But. It is an integral part of Sitecore and you can’t ignore it.

Just do the following (I know it goes against some ideals you might have):

  • Expect a user to use Experience Editor in a modern browser and on a desktop machine.
  • Hardcode certain fallbacks for when you are in Experience Editor so editing is easier for the user.
  • Use: sitecore.context.pageEditing to know if you are in fact in Experience Editor mode.

EDIT (March, 9th, 2020): I learnt that there is also a way for you to create a separate server.bundle.js file for when you have more specific needs in your app. Imagine you created a custom Svelte app or a React Native app, you need some sort of Experience Editor support. See this article for more details: https://www.adamlamarre.com/generic-server-side-rendering-for-sitecore-jss-react-native-and-beyond/

Best practice 5: Don’t go to granular with component composition.

I know React (for example) is extremely composable and hyper flexible. React developers tend to go quite granular with their component approach but it seems this is tricky with Sitecore.

The more components in components (think Xzibit from Pimp my ride) with different placeholders you go the harder it gets for a content editor to use the system. On top of that this generates extra “renderings” in Sitecore. Too many renderings make Sitecore slow. Be careful. Flatten out your architecture with less placeholders and create slightly bigger components.

Concluding

These are the top 5 things you should keep in mind when working on a Sitecore JSS project. Don’t think: “I’m a great React or Vue.js developer so I can just ingest some data and make a Sitecore JSS project work”. You are going to have a bad time.

Let go of some of your ideals. You are working on a Sitecore project not a true standalone headless app where you as a web developer choose everything. If you follow the Sitecore way you will be able to build large scale platforms for millions of users.

If you need any help. Reach out. https://twitter.com/timbenniks