Our first Sitecore Headless project

Sitecore JSS and Sitecore Headless have been out for a few years now, but we started our first headless project last year. Our chosen stack was Sitecore Headless 10.2 with Next.js SDK (19.0.0) using Server-Side Rendering (SSR). I would like to talk about two main topics in this post. The first one is how the development processes are changed because of the changed tech stack. The second part is about the technical challenges we met during the implementation.

Tech stack shift

In a traditional Sitecore MVC development the developer main skillset is around C#, .NET, and .NET Sitecore SDK and APIs. We have been using Sitecore Controller Renderings (mainly) with a Controller, Model and View to show the content. Frontend developers (mostly sitebuilders) were focussed on styling the components, but the business logic was implemented on the Sitecore MVC backend.

By using Sitecore Headless Services, most of the implementation is moving to the consumer – in our case the Next.js application. In this project, the frontend had to show data from various sources and combine the data from multiple sources:

  • The layout and the definition of the components are provided by Sitecore
  • Marketing data is provided by Sitecore – Text, Links, and Images
  • Business data is from other API sources – Azure Functions and Logic Apps with different databases in the background

As the tech stack is changed it also requires fitting our development process to resolve dependencies between tech teams and to have a seamless implementation process for each team.

Development process

As we decided not to implement any import process to Sitecore, the first and biggest challenge was to unblock the frontend development because the frontend became the only consumer to pull data from Sitecore and 3rd party APIs. This means frontend development is highly dependent on these systems. To resolve this dependency issue, we decided to…

Let me elaborate on this topic a bit. Sitecore JSS SDK by default comes with a “disconnected” mode support. Which means you (as a frontend developer) can work with YAML mock files which represents page data (layout with placeholders and renderings + rendering/page data). When the frontend is switched to “connected” mode then it can work without changing any code but using the real Sitecore Layout Service, connected to a Sitecore instance.

We took this approach and abstracted this principle, to make frontend development as independent as possible. The smallest piece in the design and implementation is the API contract. All API functions has been documented prior to development using OpenAPI. The most important parts of an API specification are the following:

  • Payload schema
  • HTTP method
  • Response schema

Using the OpenAPI documentation, the 3rd party APIs could be easily mocked using Next.js. In the Next.js environment configuration file we, as developers, could switch between mocked and live data just like Sitecore does. Not to mention that using 3rd party mock data can be used to show dummy data in Experience Editor for Sitecore authors.

So, we could resolve the development dependencies using API contracts. The next step is to find out how to synchronise the development between each team and pass full user stories for testing. Our development flow was the following:

Development process

1. In parallel:

  • 3rd party API implementation
  • 3rd party API pull request
  • Sitecore implementation
  • Frontend implementation using mocks (Sitecore, 3rd party)

2. Frontend pull request

  • The same person should review who implemented the Sitecore implementation
  • Follow-up on changes in Sitecore based on the Frontend mocks
  • Merge

3. Sitecore pull request

  • Content testing
  • Experience Editor testing
  • Merge

Based on the flow, pure Sitecore backend development changed and reduced a lot, compared to the traditional Sitecore MVC development. As a Sitecore developer, focus is shifted to implementing custom APIs, ContentsResolvers and integrations to Sitecore CM. Another important part of the Sitecore developer work is to support the frontend developers and help them to use the SDK to support Experience Editor and show them the best practices we learnt during the past few years using the Sitecore MVC. Even though Sitecore MVC is different technology, principles are similar using the Sitecore Next.js SDK and the experience from past projects is extremely useful.

Technical challenges

The main challenge is to understand the Sitecore Headless Services module and Next.js SDK as a Sitecore developer. If the basic architecture is clear, it’s time to transfer this knowledge to the rest of the team. Based on our experience, Sitecore has the best support of client libraries for Sitecore Headless. This makes it easier to understand and use it. I think the following topics should be covered while learning Sitecore as a frontend developer:

  1. How is a page built up in Sitecore?
  2. What is a layout?
  3. What are the placeholders?
  4. What is a rendering and its corresponding datasource?
  5. Most used Sitecore field types – such as text, mult-line text, link, droplink, multilist, image, etc.

After understanding these basic concepts, frontend developers can easily mock-up a page, which can be reviewed by the Sitecore team and make minor changes if needed. In general, I think it’s important to have a basic idea of each tech used on the project. It makes communication and design much easier because teams can understand each other easier, knowing these concepts.

Another challenge is hosting and choosing the right rendering method on the frontend for your project. For hosting, we had to use Azure, so we started with a simple solution – using Web App for Containers. The reason was that it’s easy to deploy and run locally as the same Docker image.

Next.js offers different rendering types. We used SSR because, 3rd party API calls should be called on the server side securely with a token and most of the content was coming from the 3rd party APIs anyway. Although - after some discussion with Sitecore community members – SSR is not the best choice with Next.js because the load is then heavy on the server side and needs scaling.


Switching to headless and using JavaScript on the client side makes the development process more seamless because of the clear boundaries in development for the different teams. Sitecore teams should focus on content structure and extensions, and frontend developer teams can focus on business logic, making the pages interactive using modern client libraries - instead of styling Razor views. I would like to also highlight that frontend development with mocks and watcher is faster than deploying .NET assemblies for each change.