First let me set the stage. We created an accelerator to build headless sites with a XM Cloud backend. We did this by creating a branch off of the Sitecore JavaScript Rendering SDK, over time we added functionality to it that we determined would be reusable over a large number of sites. In the beginning we were going to be using Vercel and we didn't know exactly what type of functionality the sites would require. Most might have blogs or news articles but not all. Some would have Sitecore Search, while others might prefer Algolia or Coveo. To facilitate this, we created a number of packages so that our clients could install the packages that they wanted. Initially we were running with yarn. Initially we also had a one size fits all style sheet which we would then modify for each of our clients.
This all worked just fine for a while…
New functionality would be introduced, and we would attempt to where possible include functional that was developed for a specific client back into the main accelerator repository. However, the changes started to come fast and furious.
Different Hosts for Different Folks and so on…
Some clients wanted to be hosted on Netlify whereas others on Vercel. So, we changed the middleware that came from Sitecore's example to be able to facilitate this based on changing an environment variable. (These were all files under the pages/api/editing if you just happen to be interested).
Another thing we needed to change was to have multiple rendering hosts. This was done by modifying the XMcloud.build.json file. In fact, we needed to have four 4 rendering hosts defined in our Jason file one for each of the production sites as well as one for each of the internal rendering hosts. Once again to interpret some of the different variations of the properties of each of these varying rendering hosts we made more code changes to Sitecore’s example.
Everybody’s got their own sense of style
Later a particular client wanted to have a multi site environment running off the same code base. All the components that we had developed would be enabled for both sites the only difference was that we needed to have different layouts and different style sheets so that it was easy to determine if a user was on the external facing site or the internal facing site. Through this we made some changes to the Layout.tsx file as well as the as well as some of the middleware from Sitecore's example. Which looked something like this:
export default function Layout({ layoutData, headLinks }: LayoutProps) {
if (process.env.NEXT_PUBLIC_SITE_NAME === 'EXTERNAL') {
return <EXTERNALLayout layoutData={layoutData} headLinks={headLinks} />
}
// Default to INTERNAL layout
return <INTERNALLayout layoutData={layoutData} headLinks={headLinks} />
}
There were also many other minor changes all over the repo.
Next some clients requested that we use some of the newer functionality that became available with a release to Sitecore example repo. Some of this functionality was specifically around using PNPM to manage packages instead of Yarn. For previous implementations changes to our package.json looked something like
"workspaces": [
"packages/*",
"sites/*"
],
"scripts": {
"build:mynewpackage1": "npm --workspace packages/mynewpackage1 run",
"build:mynewpackage2": "npm --workspace packages/mynewpackage2 run",
...
}
to a much simpler
"scripts": {
"install-build": "pnpm install && pnpm build"
}
…and then it didn’t
However, this time it didn’t work. Yarn, as we discovered, was a lot more lackadaisical as to how it managed references to the internal packages that we had created. So again, thought we had to do some remediation of a fair portion of our existing development work. That was not the case in fact we had diverged so far from the original example that it was incredibly difficult to find out where the changes need to be applied. Other smaller things we noticed didn’t work as well. Issues that Sitecore or others had gradually been remediating over time.
In attempting to be all things to all people we had really strayed from the original example. Not only was it going to be difficult to remediate this code, but it was going to be difficult to remediate it next time the example changed period. As such ultimately it became easiest to start from the latest example and then apply all of our different commits carefully to this new repo.
In Conclusion
I guess the real lesson learned here is if you are working one a branch from one of Sitecore’s example repos and you want it to be maintainable going forward you will need to move heaven and earth to try to not change any of the original files. Treat these files as your “foundational” level to use a Helix concept.