Connecting Kajoo to Sitecore XP/XM

Owned by William Hubbell (Unlicensed)
Last updated: Dec 22, 2023 by Nabil Orfali
8 min read

 

Prerequisites

You will need to have the following prerequisites to start the integration with Kajoo and start building JSS react component using Kajoo:

  1. Create a JSS site (preferably based on Next Js template) and configure the site on Sitecore.

  2. Upload your JSS app code to Github repo

Make sure the JSS app is building and launching fine on your local before checking in to repo

  1. Repo must have a prettier config file (.prettierrc) and (package.json) on the root level.

  2. Configure your JSS app on Vercel, create a project in Vercel, and link it to the GitHub repo created in the previous step

  3. To be able to view the JSS app on the Experience Editor and manage the site design you need to connect your JSS app with the Sitecore CM instance by following the instructions here: https://doc.sitecore.com/xp/en/developers/hd/200/sitecore-headless-development/walkthrough--connecting-a-next-js-jss-app-to-sitecore-editors.html

  4. Import global kajoo-stylesheet.css into your main App component or a top-level component which is typically "Layout.js/tsx" in JSS for React and "_app.js/tsx" in JSS for Nextjs.

NOTE: Without proper import, you will not be able to see the design tokens applied in UI.

  1. Experimental: If you want Kajoo to generate pages for the JSS app, you need to add this code to your JSS app.

    1. Sample usage with Sitecore Next.js JSS template

       

      Kajoo will create page layouts under "src/kajoo-layouts" path. The following steps are required to render Kajoo-generated page layouts 

      Create  kajoo layout factory under "src/lib": kajoo-layout-factory.ts

import { RouteData } from '@sitecore-jss/sitecore-jss-nextjs'; import DefaulLayout from '../Layout'; const layoutsByName: Record<string, typeof DefaulLayout> = {}; export class KajooLayoutFactory {   static getLayout = (route: RouteData): typeof DefaulLayout => {     return layoutsByName[route.name] || DefaulLayout;   };   static registerLayout = (name: string, layout: typeof DefaulLayout): void => {     layoutsByName[name] = layout;   }; }

Update "src/pages/[[...path]].tsx" to use KajooLayoutFactory

import { useEffect } from 'react'; import { GetServerSideProps } from 'next'; import NotFound from 'src/NotFound'; import { SitecoreContext, ComponentPropsContext, handleEditorFastRefresh, } from '@sitecore-jss/sitecore-jss-nextjs'; import { SitecorePageProps } from 'lib/page-props'; import { sitecorePagePropsFactory } from 'lib/page-props-factory'; import { componentFactory } from 'temp/componentFactory'; import { KajooLayoutFactory } from 'lib/kajoo-layout-factory'; import '../kajoo-layouts'; const SitecorePage = ({ notFound, componentProps, layoutData }: SitecorePageProps): JSX.Element => { useEffect(() => { // Since Sitecore editors do not support Fast Refresh, need to refresh EE chromes after Fast Refresh finished handleEditorFastRefresh(); }, []); if (notFound || !layoutData.sitecore.route) { // Shouldn't hit this (as long as 'notFound' is being returned below), but just to be safe return <NotFound />; } const Layout = KajooLayoutFactory.getLayout(layoutData.sitecore.route); return ( <ComponentPropsContext value={componentProps}> <SitecoreContext componentFactory={componentFactory} layoutData={layoutData}> <Layout layoutData={layoutData} /> </SitecoreContext> </ComponentPropsContext> ); }; // This function gets called at request time on server-side. export const getServerSideProps: GetServerSideProps = async (context) => { const props = await sitecorePagePropsFactory.create(context); return { props, notFound: props.notFound, // Returns custom 404 page with a status code of 404 when true }; }; export default SitecorePage;

 

Now you can start integrating your Sitecore instance with Kajoo by following the steps outlined on this page. The Kajoo plugin supports Sitecore 9.3, 10.0, and 10.1, with JSS versions 18 and 19. You can download the appropriate plugin for your Sitecore version on the Instances page of the Configurations screen, as described below.

 

Download and Install the Sitecore Plugin

  1. Download the Kajoo plugin from the Instances page of the Configurations screen. Go to “Configurations,” in the main Kajoo menu, then click the “Instances” tab at the top. From there, click the “Register Instance” button to download the appropriate plugin for your version of Sitecore.



  2. Install the Kajoo plugin on the target Sitecore that you want to connect to Kajoo using Sitecore update package installer (you can find it on the Control Panel)

    1. After installing the plugin, you will need to do this follow-up step:

      1. Add the required origins to the Content Security Policy header by going to the web.config file of the target Sitecore instance and adding the following origins:

        1. default-src add “cdnjs.cloudflare.com *.kajoo.ca/ *.auth0.com *.kajoo.ai”

        2. style-src add “cdnjs.cloudflare.com ”

        3. It should look like this:

          <add name="Content-Security-Policy" value="default-src 'self' 'unsafe-inline' 'unsafe-eval' cdnjs.cloudflare.com *.kajoo.ca/ *.auth0.com *.kajoo.ai; img-src 'self' data:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com cdnjs.cloudflare.com; font-src 'self' 'unsafe-inline' https://fonts.gstatic.com; upgrade-insecure-requests; block-all-mixed-content;" />

           

  3. After installing the plugin you should be able to see the Kajoo icon on Sitecore launchpad

     

When you install the Kajoo plugin to the Sitecore instance(s) of your choice, you have the option of giving the instance a custom name. When you subsequently log into the Kajoo plugin on Sitecore, you’ll be able to see both the name of the instance along with the name of the organization the instance is registered under.

Sitecore Instance Registration

  1. Open the Kajoo plugin in Sitecore. You should be prompted with a login form. Log in using your Kajoo account credentials. This step will register your Sitecore instance in Kajoo.

  2. Login to Kajoo app and then navigate to the Sites screen. In the Instances tab you should see your newly-registered Sitecore instance listed.

Configuring Deployment

The plugin needs to be installed on every Sitecore instance that you wish to deploy the Kajoo code to. These instances will appear on the instance page. From there, you can designate multiple instances as part of an Environment, and multiple Environments as part of a Site.

Environment Setup

Kajoo allows you to deploy to your environments the way you have them set up - for example, maybe you have one or multiple instances for QA, or multiple instances for Prod.

  1. Go to the Environments tab on the Sites screen

     

  2. On the Environments tab, click “Add New” to create a new Environment

     

  3. On the right-hand menu, first select the Environment type. You can select among the options of: DEV, SIT, UAT, QA, and PROD.

  4. Then, enter a logical name for the Environment, such as [Your Site Name]-QA

  5. Finally, choose among the Sitecore instances that make up this environment. There is a dropdown menu where you can see all of your Sitecore instances with the Kajoo plugin installed.

  6. Don’t worry about the Layout Services fields for now. Just enter in “test” in each one

Site Configuration - for deployment and project settings

After configuring Instances and Environments, you can configure Sites. A Site represents a specific JSS app, the codebase of which needs to be hosted on GitHub for Kajoo deployment to work. Sites can be deployed to one environment at a time from the Kajoo publishing wizard.

  1. Go to the Sites tab on the Sites screen.

     

  2. To configure a new site, click “Add New.” The Site Configuration panel will appear on the right.

     

  3. Enter a logical name for the Site: This has to be the JSS App name in the Sitecore tree.

  4. Enter the Site URL - this is not important for deployment, but is meant for the user to keep track of where the site is ultimately to be deployed.

Sitecore CM Deployment

These steps will allow Kajoo to build your JSS application and push it to the Sitecore instances of your choice.

  1. In the Site Configuration panel, select among the Environments that the Site can be deployed to. Environments must first be configured for this option to work.

  2. Click the GitHub button to connect to a code repository. Here, you will need to log in with a GitHub account, and select the Repo for your JSS Application. You must then select a Branch to push Kajoo’s output code to. We recommend making a separate branch for work being brought in from Kajoo - then you can test and merge as you see fit.

    1. Prettier: You MUST change the .prettierrc file in your repo’s app root, or deployment will fail. Change the “endOfLine” parameter value to “auto”. See more details here: Deployment Troubleshooting

Head Deployment

Head Deployment options allow you to deploy your Kajoo code directly to production.

  1. Select among your options for Deployment - Manual, FTP, or SSH. If selecting Manual, Kajoo will only check in code to your repo, build the JSS application, and push it to the Sitecore instances within a selected Environment. FTP/FTPS or SSH options will allow you to deploy the built JSS app to the Site’s head.

  2. FTP/FTPS is for apps hosted through a hosting service. This option requires specific connection information.

     

  3. SSH also requires extra connection information to connect to the host of the head. The person who configures this hosting should have knowledge of the hosting strategy for the organization and the site.

     

  4. Finally, fill in the information for the Build option: The Build Command and the Build Directory. By default the “Build” command is usually either “build” or “build:rendering host,” though these may change if the project has been customized. Similarly, the build output directory will usually be named after the build command, and is the location where the compiled JSS app will be located. This compiled app is what will be pushed to the head.

     

  5. You currently do not need to worry about the Sitecore instance fields - these are not required

     

  6. Finally, click the “save” button to save the Site configuration. You can now deploy your Kajoo components to the environments and instances of your choice!

Advanced Site Configuration

 

Some projects will have unique configurations, such as unique directories for the location of components. The Advanced Tab in the Site Configuration Panel allows you to configure non-default paths for the Component Directory, Manifest Directory, and App Entry file (the Index file for the application).

Additionally, you can use the Advanced tab to share your unique Site configurations with other Kajoo users within your organization.

Next.JS Support

Kajoo now supports the ability to pre-set deployment frameworks for Sites. If you have a JSS site that utilizes Next.JS, you now have an option in Site Configuration settings to select Next.JS as a deployment framework. Then, when you commit your project code to your repo, or deploy your project to Sitecore, it will utilize the correct Next.js code framework.