Sitecore JSS - Sitecore first

JSS - Sitecore First!

Recently I started a project where we are upgrading an existing Sitecore 9 MVC portal with AngularJS to Sitecore JSS with Angular 7. With this portal being already implemented, and content preexisting in the solution we wanted to start this with a Sitecore first approach.

In this approach we create the JSS layout service endpoint that return Json containing the same content a component now renders in the MVC controller rendering, reusing existing content, templates etc.

First things first

To start, obviously as a Sitecore developer you have to install the Sitecore JSS server components into your environment. After that you create a Sitedefinition like entry for your JavaScriptServices where you register your JSS app and set the start item for your app root. You setup your API key as defined in the JSS doc site.
To make sure your Sitecore instance is aware of this app and where in the Sitecore tree it 'lives'. You extend your Sitecore SiteDefinitions config with the app registration:

 
        <app name="personalApp"

             sitecorePath="/sitecore/content/customerName/Web/appRoot"

             inherits="defaults"

             useLanguageSpecificLayout="true"

In our case the app we work on falls in the same existing site definition as our current implementation, so the sitecorePath falls in a subpath of our site. If your's doesn't then make sure you define a site that has your approot in scope, and assign an appropriate hostname etc.

Next you create a JSS App item in your content tree as a root for your app, based on template 

/sitecore/templates/Foundation/JavaScript Services/App

 After that you create your first Route item, for us this corresponds to a page item as we referred to it in our MVC application that we are upgrading. 

This route you give a JSS layout. This JSS layout points to an empty Razor file that JSS created for you in your views folder. Apparently this Razor layout is needed for the rendering pipelines to function correctly. 

To make the layout service output actual renderings and its content in the output Json, you have to make it aware of the placeholders you will be using on the layout, so include them in your Layout definition under your Layout item's section for 'Layout Service Placeholders'.
Make sure to do the same for renderings that you expect to also have placeholders embedded, add the placeholders in the Json rendering's 'Layout Service Placeholders'.

Creating your content structure

Now that you have setup your site, layout and route. Create your Json Rendering definition item for your first rendering. Create a template for the content structure you would like it to return, just like you would create a template for a traditional Controller rendering. Of course define the datasource template on your json rendering item definition.

After this navigate to your route item.

Create an instance of your just created template under your routes' 'Components' sub item which is meant to contain all your datasource items. Assign it the right content.

Now select your route item and go to its presentation details.

Select the JSS Layout as layout and add the placeholder settings for the placeholders you expect to use on this route.

Add your json rendering and add it to the placeholder that you want it to appear in. Assign it the datasource item you just created.

Publish your site and test your route endpoint by calling:

 
{hostname}/sitecore/api/layout/render/jss?item={sitecore_item_path)&sc_lang=en&sc_apikey={your_key}

If all is in order, you should be seeing you layout service return a json containing your layout and renderings including their datasource items.

Now you are all set to hand over this layout endpoint to your frontend developer to start integrating this definition in their React/Angular/Vue app.

How do I deploy (CI/CD) all this from a (traditional) Sitecore developer perspective

As we didn't want to rely on jss deploy mechanism through our DTAP, we setup CI/CD as follows.
We use TFS to build our code and octopus to deploy to our environments.

During the server build we do a npm install.
Then we created a gulp task that builds our frontend with webpack, and that creates the dist folder for our frontend app. And gulp task tokenizes any stuff that needs to be dynamic through environments. For example the stuff in your scjssconfig.json file to set the appropriate base urls and api keys, and the environment.ts file that contains api endpoints and such.

This dist folder is then copied to our Sitecore sources web project folder.
Next step is to build and package into nuget our Sitecore solution that also includes the paths with the dist folder.

Octopus then picks up the nuget package and deploys it on the server, and replaces the tokens with the right values in the generates dist files.

An alternative for the dynamic tokens is to use environment variables, but these might be a little tricky in SSR mode where you'll have to register these in your node server, but it is possible as well.

Important gotcha's

Make sure to have upfront alignment with your frontend dev on the placeholder structure and rendering split, together with the datasource template definition. This will ease up their integration with your content definitions.

As in above setup you already defined your app and site definition there is no need to use 'jss deploy config' anymore, from your frontend code. This could potentially break your environment, and as your app and site are already registered you don't need that part. The deploysecret that 'jss deploy config' deploys is also not needed in a Sitecore first approach as you will not be using your frontend to push Sitecore items into your instance.

By default JSS uses dynamic placeholders. While this is great, make sure you think about whether or not you actually need this as this can be a bit of a nuance in a Sitecore first approach, as you would be required to construct dynamic placeholder keys for putting renderings in nested placeholders manually.
This can be achieved sub-optimially through calling your layout endpoint with the sc_mode=edit parameter:

 
{hostname}/sitecore/api/layout/render/jss?item={sitecore_item_path)&sc_lang=en&sc_apikey={your_key}&sc_mode=edit

This call will return the uid of the placeholders that you can use to construct your placeholder:
/{placeholderName1}/{placeholderName2}-{uid}-0 (/1 /2 etc.)

If you don't need dynamic placeholders you can switch back to simple placeholders by the following change:

 
In `App_Config/Sitecore/LayoutService/Sitecore.LayoutService.Jss.config` change the `/configuration/sitecore/layoutService/configurations/config[@name='jss']/rendering/placeholdersResolver` node to use the built-in `Sitecore.LayoutService.Placeholders.SimplePlaceholdersResolver`

Why would I want this Sitecore first approach?

With this approach, a Sitecore developer can be in control of how and where content is defined. This is especially helpful when creating apps in existing solutions / sites as well as for multi site definitions where content reuse is needed.