My first JSS story

 My First JSS story: the good, the bad and the undocumented

I am what you might call a typical "Sitecore developer" - started working with Sitecore when we used to create webforms, then moved to MVC based sites, then we added some SXA and PAAS.. things changed. And as you probably know, things are changing constantly and lately in a rapid pace. A few weeks ago I also started my first headless adventure. To make it a bit more exciting the project would use the -at that moment- brand new Sitecore 10.2 with JSS and Next.JS hosted with Sitecore Managed Cloud and using containers on Docker for local development. We are also integrating with a non-Sitecore DAM and Commerce solution (both headless and SAAS) but that is .. well, out-of-scope here.

Now, as I actually don't know any of these technologies except for Sitecore that would be exciting indeed. It's been ages since I wrote some Javascript, but that has become Typescrypt and React and Next and so on now. Docker is a black box and the rest is even more unknown. If this is all very familiar to you, you can stop reading. But I do assume that is not the case for everyone.

Anyway, as I'm probably not the only adventurer our there I'd though I would share my findings and maybe it can help someone in a similar situation. This is the first post - more will probably follow. I'd like to focus on the setup in this one as that is the first step in a project.

Setting up Sitecore 10.2 with JSS and Next.JS in containers

I'm afraid I can't give you an easy setup guide or simple steps to follow for what I did as it was a bit trial and error but in the end that might have been the best way to learn a bit about what I was actually doing. What I can do is give you some tips, links to the documentation pages you'll need and positive vibes to help you do the setup as well.

But first: our requirement. We want a Sitecore 10.2 with JSS and Next.js on a local setup in containers, and it should include Horizon and SXA (we want multisite options later, so people who should know advised us to add SXA - and as that is something I know I don't mind at all).

Sitecore Containers template for Next.js

Luckily -for a lot of us- Sitecore provides a template to start with. You can find the whole walkthrough in the Sitecore docs and after a few steps you can have an up and running Sitecore environment with a rendering host. The prerequisites are pretty straight forward and most developers will already have them installed. When performing the steps in the walkthrough:

• Make sure your Docker is setup correctly and running on Windows containers - it is mentioned but I noticed people still tend to forget
• Stop all processes you don't need - IIS and Solr are mentioned, you might also have some local Sitecore jobs running...
• When creating the solution in step 4, think about the parameters
• fetchWith: I have used GraphQL here which I think is the best option at the moment as Sitecore pushes this as your best plan to be future proof - we'll get back to this later
• prerender: I skipped this one to get the default SSG (static site generation)

Note that you get a script called "up" to start your environment. You can adapt this script - or create a whole new one - if needed. You could for example add "iisreset -stop". This is the script to get you started every morning and I noticed it is a good practice to end the day with a "docker-compose down" which is the command to bring down all your containers again gracefully.

Docker 

Docker.. containers..  this is the point where you should at least check some cheat sheet(s). Sitecore provides one for you and you can find lots more on the internet. If you get stuck or need to do something with a container, google is your friend and StackExchange usually the answer. But it is very useful to understand at least a bit about images, containers and some commands that are quite common.

Adding modules: SXA - Horizon

Next step: adding SXA & Horizon. Two modules from Sitecore that we want installed. 

While installing modules in a containerized setup you will learn to handle docker build and compose files. This is good, as you might want/need to customize more for your specific solution. To install modules you can find documentation on a few locations, and unfortunately not all are correct. Also make sure you are looking at documentation for version 10.2 - some things changed since that version so any old docs are not always valid anymore.

If you are reading the documentation from Sitecore on containers you are likely to first find the page on adding Sitecore modules. It uses SXA as an example, but this page is wrong. The general information in still valid but the examples are not.  Luckily there is also another page in the Sitecore Docker references that has does include the correct code. From this page you'll need to add everything for:

• Sitecore Powershell Extensions (this is needed for SXA)
• SXA
• Horizon

And yes, SXA does not need changes to the database anymore - that is correct.

After making these changes we run our start script again which will build the containers and spin them up.

Ok, so far so good. We have installed the modules but the site that was created earlier is of course not an SXA site. 

Importing the app

First of all we are going to create a headless tenant and site. This is straight forward and very easy - especially if you have some SXA knowledge. But then we have to move our JSS app into SXA and that is more on gut feeling actually. There is documentation on moving a JSS app into SXA but that was completely not relevant. So I actually started moving items into the SXA site and changing templates to from the JSS ones to the headless-SXA ones.

I did find some documentation on 10.1 that was a bit relevant on using getting started templates with SXA. I did not follow the steps exactly - in fact, I just picked the steps that made any sense:

• You do need to remove the site (and app) configuration in your code, but I did that in the end
• The part about creation your solution makes you change quite some items in Sitecore, and not all of them are actually present. Don't worry - just do the steps that can be done. The documentation is for version 10.1, and I didn't find this for 10.2 yet. Also, if you configure the settings for your app (like the "Server side rendering engine endpoint URL") make sure to use the values that are defined in the config that was created for you in your solution - do not take the values from the article.

This was a bit a trial and error step but in the end the site worked (again) so we managed. 

Issues

We bumped into quite some issues still to get our first pages working.. to a point where I as really getting ****** with all this headless **** that was not making my life easier. A few tips on Slack (and some alcohol) helped us through it. Some things I remember that might help you:

CSP header issue with Horizon

Horizon didn't work - it got blocked by CSP headers. That seemed to be a known issue described on "Content-Security-Policy frame-ancestors issue after installing Sitecore Horizon". And it was easy to fix - using web.config transformations.

GraphQL issues (with SXA)

We are using the GraphQL endpoint - which is recommended in this type of setup - but that didn't seem to work with integrated GraphQL. And you do want to use that as it is a very nice way to get data into your component. The solution was found in this kb: Nested placeholders are not rendered in Layout Service. Thank you Nick W. for you time and the solution this one.

Ok - so we removed that config file and it worked. And just for those amongst you that are container-newbies (like myself): you can delete such a file by adding this command in the Dockerfile (for cm and cd):

RUN Remove-Item -Path C:\inetpub\wwwroot\App_Config\Modules\SXA\Z.LayoutService\Sitecore.LayoutService.config -Force;

Image urls

To get image urls working, you need to set the setting IncludeServerUrlInMediaUrls to false. You need to do this on the right endpoint however. Even though we are using SXA, this is not the sxa-jss one, neither the jss one, but just the default one. Or you can patch all configs... 

Tips and tricks

1. When working with GraphQL - don't just rely on the (many) blogs out there, as the schema for the GraphQL endpoint is different compared to what is used on those blogs based on older versions. This means that some things will not be present and you need to find other solutions (e.g. images and their url including parameters and a hash). This also means however some new things are available - like sorting and paging in search queries - out of the box.
2. If your rendering contains (new) placeholders, you need to define these placeholders in the Layout Service Placeholders field in your rendering. To do this, you need to add a PlaceholderSettings item first. The field is a treelist that lets you select such placeholder setting item(s). However, it points towards the global placeholder settings folder in the layout section of Sitecore - but in SXA we define placeholders in the sites presentation area. A possible solution: get the ID of your placeholder setting item and paste it in the field in "raw values" mode.  
3. Use partial and page designs - very simple trick but saved us a lot of time again.
4.  If you need to access your Solr to test queries, you can find the ip address of the container with "docker container inspect <containername>". 

I'm quite sure there is more... so more posts will be coming in the next days, weeks...  right now we are still struggling with the Managed Cloud though 😒   

My apologies for all the text which is probably very chaotic.. just like my brain after a few weeks jumping into this containered JSS bath 😵 But if I saved anyone some time in their Sitecore endeavor it was worth it. 

Hoping to read more adventures on Sitecore JSS 10.2 with NextJS soon and see you all in Budapest.