Forem: Thomas Desmond

Cloudflare Pages and Next.js: I'm Not Recommending It

Thomas Desmond — Wed, 01 May 2024 14:28:48 +0000

As a developer, I am always looking for ways to test the limits of different hosting providers and see how well they support different frameworks and technologies. I recently tested Cloudflare Pages with my Next.js app, and the results differed from what I expected. In this article, I'll walk you through my experience and the changes I had to make to get my app to work on Cloudflare Pages.

Next.js Host Check App

Before I dive into my experience with Cloudflare Pages, let me give you some background on my app. I have built an app that tests 13 of the most essential features of Next.js Pages Architecture. These features include server-side rendering, image optimization, and API routes, among others. I've put Cloudflare Pages to the test. I'm deploying this application on different hosting providers to see how well they support Next.js and what features they do and don't support.

My app is a Next.js Pages Architecture application built with version 13.4.16. I attempted to deploy it out of the box to different hosting providers. However, I ran into some difficulties with Cloudflare Pages.

GitHub: Host-Check-Next.js

My Experience with Next.js on Cloudflare Pages

The biggest thing I came across was the edge runtime requirement. All server-side routes in your Next.js project must be configured as edge runtime routes. When running on Cloudflare Pages, you must add export const runtime=edge to each server route.

This means you are limited to the edge runtime for Incremental Static Regeneration (ISR), getServerSideProps(), API Routes, and everything else server-side.

❓ What is the Edge Runtime? From Vercel, the edge runtime provides a subset of web APIs such as fetch, request, and response. This lightweight API layer is built to be performant and execute code with minimal latency. See Vercel's documentation for a full list of available APIs.

So, I added the line export const runtime=edge to every file, but the build still failed. Instead, I had to use export const runtime=experimental-edge, which got my Next.js app to at least build in Cloudflare Pages.

But that was not the end of my problems. I had to add a nodejs_compat flag within Cloudflare Pages. I'm not sure why, but I did.

After one more final rebuild, my app was built and deployed correctly. I could access my application live and deploy it to the web. Finally, it was time to test what features of Next.js worked.

Next.js Feature Support in Cloudflare Pages

With the host-check-nextjs app deployed to Cloudflare Pages, I could now run the automated Cypress tests against the deployed app.
Here are the results of the automated testing. These are the worst results so far in my testing of Next.js hosting providers.

Next.js Feature Support
Next.js Version 13.4.16 Pages Architecture	✅
getStaticProps()	✅
getServerSideProps()	⚠ (Edge Runtime Only)
Image Optimization	❌
Incremental Static Regeneration (ISR)	⚠ (Edge Runtime Only)
API Routes	❌
Middleware Redirects	⚠ (Edge Runtime Only)
Edge Runtime	✅
Dynamic Routes	⚠ (Edge Runtime Only)
next.config.js Redirects	✅
next.config.js Rewrites	✅
Sub-path Internationalization	✅
Sitecore JSS Image Optimization	❌

While still working, the edge runtime limits anything that runs on the server, like ISR and getServerSideProps(). You can also see standard API routes are not working and no out of the box image optimization.

The absence of image optimization is a major issue for me. Optimized images are essential to creating a modern and efficient website. The fact that Cloudflare Pages does not utilize the built-in next/image components, which are designed to optimize images for the web, is a deal breaker. This could lead to slower page load times and a less optimal user experience.

Conclusion

In conclusion, my experience with Cloudflare Pages and Next.js was challenging, but I got my app to work with some specific changes. Cloudflare Pages only supports the edge runtime for its server-side routes, so you are limited to the available APIs. However, Cloudflare Pages might be perfect if you're looking for a more performant edge runtime with a smaller minimal latency API layer— I don't expect the number of people with that specific need to be very high.

Understanding the limitations and requirements when working with Cloudflare Pages and Next.js is crucial. This post aims to provide you with valuable insights from my experience, equipping you with the knowledge you need for your own testing and deployment of Next.js apps.

Interested in other Next.js hosting providers? Check out my other test runs:

AWS Amplify Support for Next.js

How Well Does Azure Static Web Apps (SWA) Support Next.js?

Or watch the video version of this article: Why Cloudflare Pages May Not Be the Best For Next.js 🤷‍♂️

How Well Does Azure Static Web Apps (SWA) Support Next.js? | Pages Architecture

Thomas Desmond — Wed, 10 Apr 2024 14:33:09 +0000

I have developed an application that focuses on isolating and testing the most essential features of Next.js. After creating the app, I deployed it to Azure Static Web Apps (SWA). Recently, SWA updated its platform, and I was excited to see how their improvements have impacted Next.js. To my surprise, the improvements were impressive.

💡 The current app uses the Pages-based architecture; I plan to develop an App Router Next.js application very soon. Give the repo a ⭐.

Next.js Application Overview

The Next.js application I deployed is publicly available and open-source on GitHub.

Essential factors of the app:

Next.js version 13.4.16
Pages-based Architecture
Sitecore JSS version 21.6.3

For more details on the app, check out my earlier article: Exploring Every Feature in Next.js and Testing Hosting Providers or YouTube Video: Using Every Next.js Feature to Test Hosting Providers (Part 1).

How I Deployed the Next.js Application

I followed the Deploy hybrid Next.js websites on Azure Static Web Apps (Preview) documentation to deploy my app. I didn't make any configuration changes, so it was an out-of-the-box deployment of Next.js to Azure Static Web Apps.

Although Next.js support has been in preview on Azure SWA for years, this latest release makes me expect it to be out of preview soon. However, I am not hosting production Next.js applications in SWA since support is still in preview.

Next.js Support in Azure Static Web Apps

I was presently surprised that Azure Static Webs Apps had full support for every feature I tested. I ran my automated Cypress tests against the deployed Next.js app, and every test passed.

Check out the table to see every feature tested and the results.

Next.js Feature Support
Next.js Version 13.4.16 Pages Architecture	✅
getStaticProps()	✅
getServerSideProps()	✅
Image Optimization	✅
Incremental Static Regeneration (ISR)	✅
API Routes	✅
Middleware Redirects	✅
Edge Runtime	✅
Dynamic Routes	✅
next.config.js Redirects	✅
next.config.js Rewrites	✅
Sub-path Internationalization	✅
Sitecore JSS Image Optimization	✅

Based on the test results, Azure Static Web Apps is a suitable platform to host a Pages-based Next.js application on version 13. However, it's important to note that SWA Next.js support is still in preview, so it's not recommended for production deployments yet.

I tested a pages-based Next.js 14 app, which failed due to Node version issues. I haven't investigated further, but Node 14 deployments do not work out of the box for now.

How to Test Hosting Providers Yourself

Want to test Azure Static Web Apps for yourself? Have a specific version of Next.js that you need to test.

Fork my open-source repository on GitHub: https://github.com/thomas-desmond/host-check-nextjs
- Remember to give the repo a star! ⭐
Deploy the Next.js to your hosting provider
Change the url environment variable in the cypress.config.ts file
Run the automated Cypress end-to-end tests and see the results
1. Open cypress test window npm run cypress:open
2. Choose E2E Tests
3. Choose your preferred browser
4. Run all the specs (tests)
5. Review the results of the tests

Watch the YouTube video version of this content: Testing Azure Static Web Apps Support for Next.js | Pages Architecture

Exploring Every Feature in Next.js and Testing Hosting Providers

Thomas Desmond — Wed, 13 Mar 2024 16:40:17 +0000

Today, I want to share with you a project I'm currently working on - a new Next.js project that will use every feature of Next.js. Join me as I delve into the intricacies of this project, exploring every feature that Next.js has to offer.

The Project Overview

In this project, I utilize every feature of Next.js, from statically rendered pages to API routes and everything in between. My focus is not just on showcasing these features but creating an app where each feature is isolated and individually testable. Why is it individually testable? The goal is to test various hosting providers to see how well they support these Next.js features.

We know the big two, Vercel and Netlify, have fantastic support for Next.js. But what about all the others popping up? AWS Amplify? Azure Static Web Apps? Cloudflare Pages? How well do they support Next.js' plethora of features?

I'm using the Pages-based architecture of Next.js for this first run and hope to have enough support to take on App router features next.

Testing and Automation

Unlike traditional projects, my approach is to build an app that isolates each feature to a page, making it easier to test and evaluate. This allows me to generate a report on what is actually supported and working on any given hosting provider. So far, I have tested eleven of the Next.js features.

I am creating automated Cypress end-to-end tests to assess each feature of Next.js. The plan is to host the test application on a hosting provider of your choice and then direct the Cypress tests toward the hosted solution. By determining which tests pass or fail, you can gain insight into the hosting provider's capabilities and compatibility with Next.js features.

Future Prospects

My vision for this project is to create a robust platform that provides insights into the compatibility of Next.js features with various hosting providers. This can help developers make informed decisions when choosing a project hosting platform.

Give developers confidence that the version and features of Next.js that they require work before they go too deep into their solutions.

Join Me on this Journey

Please follow along as I continue to develop this project. Your feedback and insights are invaluable as I strive to make this app a comprehensive testing ground for Next.js features. I want to make sure this app is helpful to everyone, not just myself.

Share your thoughts on the features you use in your Next.js applications and the hosting providers you are considering.

Stay Tuned for More

If you're intrigued by this project and want to see how it unfolds, consider subscribing to my new YouTube channel, Thomas Does Dev. That is where I'll have the most up-to-date information on this project.

In the upcoming parts of this series, I'll explore new features and test different hosting providers.

Check out the code: Next.js Every Feature

Watch the video version for even more details.

Vercel and Netlify's Convenience Layer: Simplify Your Frontend Workflow

Thomas Desmond — Wed, 17 Jan 2024 18:52:06 +0000

As a web developer, I've always been on the lookout for hosting services that provide more than just a simple server to host my applications. I wanted a platform that could offer a bunch of additional features that could help me streamline my workflow. This is where Vercel and Netlify come in.

Both Vercel and Netlify have a lot to offer, and I've been using them for quite some time now. In this article, I want to talk about the convenience layer that both Vercel and Netlify offer, and why I recommend them to anyone looking for frontend hosting.

What is the Convenience Layer?

The Convenience Layer refers to a range of services and features that Vercel and Netlify offer to developers to improve your frontend workflow. These platforms offer more than just hosting services. They provide a comprehensive range of development, review, deployment, production, and scaling features. These features go beyond the JavaScript frameworks you are building on like Next.js, React, Astro, etc.

In fact, Vercel now refers to itself as the Frontend Cloud and Netlify refers to themselves as a Composable Web Platform. Both these names imply they are much more than just a hosting service.

Let's take a closer look at some of these features that make up the Convenience Layer.

Development Features

Both Vercel and Netlify offer development features such as development servers, CLI's, and starter templates. These features help developers to quickly set up a new project and start working on it without having to worry about server configurations and other technical details.

Netlify Starter Templates

Vercel Starter Templates

Review Feature

Vercel and Netlify also offer a review feature that allows developers to set up staging servers and automated builds for branches. This enables developers to test their code changes before pushing them to production.

Vercel offers a feature where others can leave comments directly on the page of preview deployments. Allowing non-technical users to easily provide reviews of your changes.

Deployment Features

Continuous integration and deployment are two critical features that both Vercel and Netlify offer. These features allow developers to automatically deploy their code changes to production without having to worry about manual deployments. The instant rollback in both providers also gives you that safety net should you need it.

Production Features

Vercel and Netlify also offer a bunch of production features such as secure environment variables, On-Demand Incremental Static Regeneration, and analytics. These features help to protect sensitive data, cache frequently requested pages, and analyze website traffic and user behavior.

Netlify also exclusively offers Split Testing, which lets you divide traffic to your site between different deploys, straight from their Content Delivery Network (CDN)

Scaling Features

Finally, Vercel and Netlify offer a range of scaling features such as DDoS protection, caching, content delivery networks (CDN), image optimization, and localization. These features help developers to scale their applications and handle large amounts of traffic without any issues.

Vercel and Netlify can take so much work off your hands with the Convenience layer. Stop worrying about deployment servers, where to store your environment variables, how you'll distribute your application globally. Embrace the convenience layer.

Scenario Taking Advantage of the Convenience Layer

Let's take a look at a complicated deployment and hosting scenario that gets cleaned up when the developers embrace Netlify. Keep in mind these same results are achievable in Vercel.

Turn This Complicated Workflow:

Into Something Much Simpler with Netlify:

Consolidate services like development servers, automated builds, CI/CD, CDN, and much more, all into Netlify. This simplifies your tooling so much. With everything in one location you can have faster time to market, faster iterations, and a robust infrastructure powered by Netlify.

💡Keep in mind this is again all achievable and a similar solution in Vercel.

Why Choose Vercel and Netlify?

If you're looking for a hosting platform that can offer you more than just a simple server, then Vercel and Netlify are the perfect options for you. With their range of features, you can streamline your frontend development workflow and focus on building great applications without worrying about technical details.

In conclusion, I highly recommend Vercel and Netlify to anyone looking for frontend hosting services. Try them out today and see for yourself how much they can improve your development workflow.

Still not convinced? You can check out other Next.js hosting providers in my other article: Beyond Vercel: Hosting Alternatives for Next.js but none of them will compare to the offerings provided by Vercel and Netlify.

Beyond Vercel: Hosting Alternatives for Next

Thomas Desmond — Fri, 12 May 2023 16:53:44 +0000

Next.js has gained significant popularity as a frontend framework. And rightly so. Next.js has a solid developer experience, lots of features, and is flexible enough to work for many use cases.

And with Next.js comes Vercel, the maintainers of Next.js and the go-to platform for hosting your Next.js applications. You’d think since Vercel built Next.js and continues to add features wouldn’t Vercel be the best hosting solution?

Yes, Vercel is a great choice, but it’s prudent to understand that there are other hosting options out there that go beyond Vercel. In this article, we will explore alternative hosting solutions for your Next.js app. You need to host your awesome application to show it to the world, so learn where that hosting makes the most sense for you.

For all the Sitecore Headless Services readers, the hosting options listed below can support your Next.js Headless Services built applications.

Hosting Options

When choosing your hosting consider things like support for advanced Next.js features such as Incremental Static Regeneration (ISR), middleware, and serverless functions. Also, consider the developer experience, costs, and scalability.

Comparing options for an enterprise setting? Make sure you look into things like security compliance, single sign-on (SSO) integration, and dedicated customer support.

The two standout alternatives are Netlify and Amazon Web Services (AWS) Amplify. The out-of-the-box support for Next.js features, built-in content delivery network (CDN), and other nice-to-haves of Netlify and AWS Amplify make them great choices. Microsoft’s Azure Static Web Apps is another choice; you can even self-host. Let’s jump into the hosting options.

Hosting Next.js on Netlify

Netlify deserves its own category because it is the most similar to Vercel. Netlify is one of the most popular web hosting platforms, especially for Jamstack applications. Like Vercel, Netlify can host the most popular frontend frameworks, including Next.js, React, Angular, Nuxt, Vue, and more.

Netlify has its own content delivery network (CDN), support for Next.js serverless functions, Incremental Static Regeneration (ISR), Middleware, Image Optimization, and more. The Netlify team works hard to provide a fully featured Next.js experience.

Netlify, in my opinion, is the closest and most worthy competitor to Vercel. For more information check out Next.js on Netlify.

Next.js with AWS Amplify

Maybe you want more control over your deployment workflow, want to stay in your existing cloud environment, need more granular control of your application, or some other reason. You may find yourself considering AWS Amplify.

AWS Amplify provides a complete solution for hosting a globally distributed Next.js application. It supports all the biggest Next.js features, including SSR, API routes, middleware, ISR, and image optimization. Meaning less infrastructure setup and maintenance for you. The developer experience is not as seamless as Vercel or Netlify, but I see improvements being made.

Find their Next.js hosting tutorial here: Deploy a Next.js 13 app to AWS with Amplify Hosting.

💡 Vercel, Netlify, and AWS Amplify are my recommendations for hosting Next.js. They all have purpose-built solutions for hosting globally distributed Next.js apps and support the best features of Next.js.

Microsoft Azure Static Web Apps

I know many people are in the Microsoft Cloud ecosystem, so I want to mention the Microsoft solution Azure Static Web Apps.

You may have noticed Static Web Apps is not currently one of my recommended hosting platforms. It does not currently support many of Next.js’ more advanced features. There is a public preview available that claims support for zero-config setup, SSR, ISR, API Routes, Image optimization, and more. But I would not consider this public preview ready for production enterprise Next.js apps.

Hopefully, in the future, when no longer in preview, I can add Azure Static Web Apps as a recommendation for Next.js hosting. For now, it’s better to hold off.

Here is a recent video detailing the public preview: Enhanced Hybrid Next.js Support in Azure Static Web Apps.

Dedicated Node.js Hosting & Self-Hosting Next.js

The last hosting option is dedicated Node.js Hosting and Self-Hosting. This is only for when you need complete control of your Next.js application and also want full responsibility for the maintenance. I stay very far away from this because I do not want to maintain my own CDN, I don’t want to deal with all the infrastructure, and I don’t want to set EVERYTHING up.

The platforms you may use if you are in this category could be an AWS EC2 instance, Digital Ocean, Heroku, or, heck, it could be your own laptop. At its most basic, the workflow here is that you would run next build to generate the static HTML files. Then host them on the platform of your choice.

Don’t make things harder for yourself than they need to be. Consider your top three options Vercel, Netlify, and AWS Amplify.

Conclusion

While Vercel is an exceptional choice for hosting Next.js applications, it's essential to recognize that alternative options are available to suit your specific needs and preferences. Determine what is most important to you and your situation, then choose what fits best.

Support for advanced Next.js features, developer experience, and not having to maintain a globally distributed infrastructure are most important to me. That’s why I have recommended Netlify and AWS Amplify as alternatives to Vercel. Choose any of the three, and you’ll have a fast, secure, and scalable Next.js app. Vercel, Netlify, and AWS Amplify can all support a Sitecore JSS at an enterprise scale.

If you do choose one of these three or even something else, reach out to me and let me know why you made your decision.

Next.js App Directory Architecture First Impressions

Thomas Desmond — Mon, 06 Mar 2023 19:52:57 +0000

Thomas Desmond here, Developer Advocate at Sitecore. Recently I’ve been intrigued by the new Next.js app directory architecture released in beta with Next.js 13.1. So I set out to build a proof-of-concept app trying out the new architecture in Next.js.

I decided to build a clone of the Vercel Commerce app using Sitecore OrderCloud and the new architecture. I want to give my early impressions of the new architecture and talk about documentation, shifting your mindset to Server Components versus Client Components, package support, and lastly, should you migrate to the new architecture.

Let’s jump in!

1. Documentation

I started my journey into the app directory architecture by reading the documentation. It excited me to see what was possible with the new architecture in Next.js. It was well thought out. And it even uses Vercel’s new page preview feature where visitors can leave comments directly on the page, and you can see your and others’ comments.

This was super helpful because it added clarity to certain sections or you could directly comment about support for different features.

I’d like to add that the documentation is positioned well for someone transitioning from pages-based architecture—lots of comparing old versus new.

To close out documentation, I’d like to add that since this is a very new and BIG change to Next.js. There is not a lot of community documentation…yet (blog posts, videos, tutorials, starter kits). You will likely read GitHub issue threads if you encounter something new or unexpected.

2. Server Components vs. Client Components

One of the biggest changes in the new app directory is that all components are Server Components by default. A server component is a component that renders entirely on the server—leveraging the power of the server to fetch data and reduce dependency requirements for the client.

Ideally, you use Server Components as much as possible to reduce the load on the client. So you want to think with Server Components in mind.

Server Components are great, but they can’t do everything. Specifically, they cannot contain client interactivity. A component built and rendered by the server cannot contain client code. For example, useState, useEffect, onClick all cannot exist inside a Server Component.

Next.js does a great job of showing you an error if these sneak their way into one of your Server Components, but you’ll learn quickly what can and cannot be done in a Server Component.

It’s easy enough to tell a component that it is a Client Component with the new use client directive that you add to the top of your file. This tells Next.js that this component has client interactivity and needs to be a Client Component. The functionality of a Client Component is that it is pre-rendered on the server and then hydrated on the client.

'use client'
import { useState } from 'react';

export default function Counter() {
  const [active, setActive] = useState(false);

  return (
    <>
    // Your code here
    </>
  );
}

At first, I thought putting use client in many of my files indicated I was doing something wrong. But in the previous pages architecture, everything was a Client Component. So it may just be that I am a little used to the old architecture and not fully thinking with my Server Component hat yet.

But some of the packages and libraries I like to use in Next.js require using Client Components, which was a big reason for me having the use client in many files.

So that leads me to Package Support

3. Package Support

A new architecture is a serious change. This is a breaking change for some packages and libraries.

An early difficulty I encountered was using UI component libraries like Mantine and Material UI in the new architecture. After looking through some GitHub issues, the culprit is Emotion, a package many component libraries rely on that does not support server rendering.

With a custom initialization setup, I did get Mantine working for my Client Components. But that meant any component with UI was going to be Client Components, not taking advantage of those Server Component benefits.

It’s unclear if Emotion will or can ever support being Server Rendered, but they are aware of the problem and have issues open tracking how they want to move forward.

Mantine with Next.js 13 app dir Issue #2815

Emotion: Plans to support Next.js 13 - /app directory Issue #2928

This was the only major package support hurdle I had to take on, but it did take custom code, and even the Mantine team says it’s not fully tested or supported in its current state.

Bringing in simpler packages that didn’t require setup or initialization worked out of the box, so most of your packages and libraries should be supported. However, it’s worth checking with the developers or maintainers to see if the new app directory is supported.

It’s worth noting that currently, the recommended UI styling choice for the app directory is to use CSS or tools that generate CSS like Tailwind. Component libraries like Mantine and Material UI do not take full advantage of new app directory features.

4. Migrate now or later?

Finally, we are at the question. Should you migrate to the new architecture?

The short answer is no

At the time the app directory architecture is still in beta and not recommended for production.

But if you are a Next.js user and plan to continue using Next.js, I think it’s a good idea to start poking around and experimenting with the new architecture. Maybe build a small side project with it to get a feel for it.

Or the page architecture and app architecture can work together. It’s not one or the other. So you could consider building out your next feature in the app directory. Keep all your existing app functionality in the pages directory but get a feel for the app directory changes by building a new feature.

Overall I like the new architecture. It looks like it will allow for more options when building your pages and components to mix and match static versus dynamic content. It’s a big change for Next.js but a step forward in allowing you to do more.

Client Components and use client in Next.js App Directory

Thomas Desmond — Thu, 02 Feb 2023 20:31:41 +0000

Are you considering using the latest Next.js 13 feature, the new app folder-based architecture? Finding yourself adding the use client directive in lots of files? Or hitting this error:

Error: 

You're importing a component that needs useEffect. It only works in a Client Component but none of its parents are marked with "use client", so they're Server Components by default.

   ,----
 1 | import { useEffect  } from 'react';
   :                                                                                          ^^^^^^
   `----

By default, every component in the Next.js app directory will be a Server Component. Server Components are excellent. There are many reasons for them to be the default, but now you must explicitly tell Next.js when you have a component that needs client interactivity. Not everything can be done sever-side. That’s where Client Components come in.

Declaring a Client Component

To fix the above error, you must make your component a Client Component. To declare a Client Component, you add the use client directive to the top of the file.

'use client'
import { useState } from 'react';

export default function Counter() {
  const [active, setActive] = useState(false);

  return (
    <>
    // Your code here
    </>
  );
}

The component above requires use client because it has useState in it. The state cannot be handled server-side. Other common reasons to have use client would be if your component uses useEffect, useRef, or onClick.

Depending on your application requirements, you may add use client to several of your components. Adding use client is okay, but it is good to understand what adding use client does to your components.

What does `use client` do in Next.js?

Adding the use client directive turns a component into a Client Component. A component must be a Client Component if it requires client-side interactivity (useState, OnClick, etc).

💡 The Next.js documentation states: You can think of Client Components as how Next.js 12 and previous versions worked (i.e. the pages/ directory). https://beta.nextjs.org/docs/rendering/server-and-client-components#client-components

How is a Client Component rendered?

A Client Component is pre-rendered on the server and hydrated on the client. Now, this is where I needed clarification, so I did the research and wrote this article.

What does it mean to be pre-rendered on the server and hydrated on the client? Are client components only rendered partially client-side?

Pre-rendering vs. Hydration in Next.js

Pre-rendering is when HTML is generated in advance (server-side or during build time) with minimal JavaScript.

Hydration occurs once the page gets loaded into the browser. JavaScript gets executed, and your component becomes interactive.

So a Client Component isn’t entirely client-side. Next.js tries to do as much work as possible in the pre-rendering step to alleviate the work required client-side. Pre-rendering the HTML in advance without interactivity. Then, hydrate that HTML structure with the event handlers and interactivity.

There are two forms of pre-rendering in Next.js: Static and Server-Side. Static or Server-Rendered is determined by how you fetch your data in Next.js.

  const staticPreRendering = await fetch(`https://...`, { cache: 'force-cache' });

  const serverPreRendering = await fetch(`https://...`, { cache: 'no-store' });

Before the Next.js 13 app directory architecture, the pre-rendering method was determined by getStaticProps or getServerSideProps.

You can learn more about how data fetching has changed in Next.js 13 in a previous post of mine 3 Big Changes in The New Next.js App Folder Architecture.

Does having `use client` mean I’m using Next.js 13 wrong?

No.

Before the new app directory architecture, every component was a Client Component. Now that Server Components have been introduced, the distinction between Client Components and Server Components is essential, but having Client Components does not mean you are using Next.js 13 wrong.

Try to use Server Components as much as possible in your application. One benefit is that they help reduce the amount of JavaScript required on the client, thus speeding up performance. The best way to ensure you use Sever Components is to build small single-purpose components. Single-purpose components will help you separate components needing client-side interactivity and those not.

💡 For more on why you should use Server Components whenever possible, check out: What and Why: React Server Components in Next.js 13.

Closing

Building with the new Next.js 13 app directory architecture means you must learn to use the use client directive. Having use client in your application is inevitable. I cannot imagine having a real-world application built with Next.js that does not need useState or useEffect in a component.

If you put use client in every component, you may need to reconsider your architecture and separate your components more.

Want more content about the new Next.js 13 architecture? Check out 3 Big Changes in The New Next.js App Folder Architecture.

3 Big Changes in The New Next.js App Folder Architecture

Thomas Desmond — Tue, 17 Jan 2023 17:45:53 +0000

With Next.js 13 the app/ folder architecture was released in beta. The goal with the architecture is to make Next.js development easier, faster, and ship less JavaScript to the client.

The new architecture is a big change to Next.js as it changes how you architect your application from the ground up. Luckily, the traditional page/ folder based architecture is still supported and will likely still be supported for a while.

However, it’s important to look at what the future of Next.js looks like. So let’s cover the 3 biggest changes you want to be aware of in the new Next.js app/ folder-based architecture.

Component Rendering
Data Fetching
Routing

The changes to these three categories will be the focus of the article.

❗ Important: Next.js 13 still supports the previous architecture with all pages in the pages/ directory. And actually as of right now the new app/ based architecture is still in beta and not recommended for production. It is currently possible and I would encourage using the pages/ and app/ architectures side by side.

The Architecture

Before jumping into the 3 big changes let’s first cover the biggest change: The Architecture itself. The big change is that your application will now be built inside an app/ folder. As I have mentioned you could continue to build and use what you have in your pages/ folder. But if you are building new features and on the latest version of Next.js consider moving to the app/ folder. The pages and app architecture were designed to be used in conjunction.

app/
├─ layout.js
├─ page.js
├─ error.js
├─ loading.js
├─ products/
│  ├─ page.js
│  ├─ loading.js
node_modules/
pages/
├─ api/
├─ app.js
public/

Inside the app/ folder is where you get access to all the new features of Next.js 13. It may seem like a daunting task to re-architect your application but becoming familiar with the changes is the first step.

Component Rendering

By default, the app/ directory uses Server Components. The biggest reason for this is that the more you can render on the server the less JavaScript needs to be sent to the client

The server has limitations that the client does not and vice versa, so you can still create client-side components in Next.js. If you need access to things like useState or useEffect that will need to be a client component. You declare a client component by adding 'use client' at the top of your component.

'use client'
import { useState } from 'react';

export default function Counter() {
  const [active, setActive] = useState(false);

  return (
    <>
    // Your code here
    </>
  );
}

So you will be mixing and matching server with client components in your application. Server components are the default and thus should be used whenever possible. This encourages component-driven development. Ensuring that you separate logic that requires the client and the logic that can be executed on the server.

I’m excited about this feature and looking forward to leveraging the server more. I do think it adds complexity as you will need to design with a server vs client approach. Don’t take the easy way out and mark everything as use client and lose out on all the server-side benefits.

This change will require some getting used to if you are coming from the traditional Next.js architecture but the improvements Server Components can provide are worth the effort.

💡 Want to learn more about Server Components? Check out this previous article: What and Why: React Server Components in Next.js

Next.js Documentation on Rendering Fundamentals

Data Fetching

The new architecture simplifies data fetching by moving to a more standard async/await approach using the fetch() API. This means no more getServerSideProps or getStaticProps.

This also allows you to fetch the data you need at the component level. This is a big improvement in Next.js. No more fetching at the page level and passing data deep down different component layers. Fetch the data when and where you need it.

So now when it comes to building a page in Next.js you don’t need to first ask: “Will this page be static or dynamic?” You now have the ability to mix and match dynamic and static components in a single page.

Whether a component is dynamic or static is determined by a cache property on your fetch().

force-cache: The default and will generate a static page, the equivalent of getStaticProps
no-store: Data will be fetched with each request, the equivalent of getServerSideProps

export default async function Page() {
  // This request should be cached until manually invalidated.
  // Similar to `getStaticProps`.
  // `force-cache` is the default and can be omitted.
  const staticData = await fetch(`https://...`, { cache: 'force-cache' });

  // This request should be refetched on every request.
  // Similar to `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' });

  // This request should be cached with a lifetime of 10 seconds.
  // Similar to `getStaticProps` with the `revalidate` option.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  });

  return <div>...</div>;
}

The last fetch() example in the code above shows how Incremental Static Regeneration can be achieved with the new fetch() paradigm.

This change of using fetch() instead of getServerSideProps and getStaticProps is not a huge change but you will have to adapt to the new syntax and structure when fetching your data.

Next.js Documentation on Data Fetching

Routing

Routing has been improved with support for layouts, nested routing, loading states, error states, and more.

The new routing strategy builds upon the file system-based routing previously available. So what's inside your app/ folder determines your routes but now there are more special files that determine the UI for your route. Note: I am using the .js file extension but .ts, .jsx, or .tsx are also valid.

page.js: Required for every route. Defines the UI and makes the path publicly accessible. Here is where you will bring all the components together to form your page.
layout.js: Required at the root level. Used to define the UI across multiple pages. A great example would be your navigation bar. A neat feature is that layouts preserve state and do not re-render if the page you route to has the same layout.
loading.js: Optional displayed when a loading state is active for the page. Used in conjunction with React Suspense to show loading states.
error.js: Optional gives you the ability to isolate errors and choose what to show if an error does occur.
head.js: Optional in this file you define what you want in the <head> tag component.

So for each route, you need a page.js file. The layout.js is required only at the root but can be left out of subsequent routes. The others are there to enhance reusability and separate concerns. Below is a possible routing structure inside your app/ folder.

app/
├─ page.js
├─ layout.js
├─ error.js
├─ loading.js
├─ profile/
│  ├─ page.js
├─ admin/
│  ├─ page.js
│  ├─ error.js

You can store components, styles, tests, or really anything else in the routing folder structure as long as they do not conflict with the special file names in Next.js.

Hopefully, this change does not cause too many issues for you if you are migrating from traditional Next.js architecture. You will need to embrace the new page.js naming convention and possibly move logic around for your loading and error-handling states. This does provide a better separation between your page's different states.

Next.js Documentation on Routing

Closing

So the big changes happening in the new Next.js app/ folder-based architecture are how you do component rendering, data fetching, and routing in your applications. With the focus on leveraging the server as much as possible.

The new rendering process should help reduce the amount of JavaScript required by the client, leading to faster sites. The new data fetching process is more in line with standard React data fetching practices and allows for fetching at a component level. Routing doubles down on the file-system-based routing and supports new Server Components push in the new architecture.

Accessing JWT and Session Data in NextAuth.js with Callbacks (Okta Example)

Thomas Desmond — Tue, 03 Jan 2023 19:23:57 +0000

Do you have NextAuth.js working in your Next.js app but need to extend the functionality with callbacks? You are in the right place. In this article, I’ll show you how NextAuth.js provides callbacks to give you greater control of your authentication. You will see examples with JSON Web Tokens (JWT) and Session callbacks, and these translate well to the other callbacks available in NextAuth.js. I’ll be showing off with Okta as the auth provider, but if you are using a different provider you’ll benefit from this as well.

If you are still setting up NextAuth.js, you can follow my previous post, Adding Authentication to Nextjs with NextAuth.js and Okta. It uses Okta as well for the examples but is generic enough to help you set up for any provider.

Callbacks in NextAuth.js

Callbacks are asynchronous functions that NexAuth.js exposes so that you can execute your own logic when an action is performed. Each callback has specific criteria for when it will run covered below.

There are 4 callbacks that you have access to and we will be focusing on the top 2.

JWT callback
Session callback
Sign in callback
Redirect callback

You access these callbacks and write your logic in the pages/api/auth/[...nextauth].ts file. Below is a code example with empty JWT and session callbacks.

// pages/api/auth/[...nextauth].ts
import NextAuth from 'next-auth';

export const authOptions = {
    // Configure one or more authentication providers
    providers: [
    ],
    session: {
    },
    secret: process.env.SECRET as string,
    callbacks: {
        async jwt({ token, account }: any) {

        },
        async session({ session, token }: any) {

        }
    }
};

export default NextAuth(authOptions)

The JSON Web Token (JWT) Callback

This callback is called whenever a JWT is created or updated. The return value will be encrypted and stored in the client machine's cookie information. You are likely using the JWT to authenticate with another service so let’s take a look at how you can access and decrypt your JWT.

// pages/api/auth/[...nextauth].ts
...
callbacks: {
    async jwt({ token, account }: any) {
        if (account) {
            token.accessToken = account.access_token;
            token.idToken = account.id_token;
            token.oktaId = account.providerAccountId;
        }

                // Decrypting JWT to check if expired
        var tokenParsed = JSON.parse(Buffer.from(token.idToken.split('.')[1], 'base64').toString());
        const dateNowInSeconds = new Date().getTime() / 1000
        if (dateNowInSeconds > tokenParsed.exp) {
             throw Error("expired token");
        }

                return token;
    }
...

First, you validate if the account exists. The account refers to the authentication provider, which in my case is Okta. It then takes the required account information and stores that in the token. You can debug or console.log to see what all information is available for your provider in the account variable.

Second, the token is decrypted so you can check the expiration. If the token is expired an error is thrown. You may want a more delicate solution but this gives you the groundwork for decrypting and checking values in the JWT callback.

💡 The above code has Okta-specific provider variables. The information accessed from the account variable is going to be information about the user's Okta account. If you are using different providers it’s important to verify the naming conventions used by your provider. For example, id_token may be idToken instead.

NextAuth.js JWT Callback Documentation

Session Callback Example

The session callback is called whenever a session is checked. So any calls to getSession(), useSession(), & /api/auth/session.

Inside the session callback, you can extend what data is returned to you whenever the session is checked. In my use case, I needed the user's oktaId passed through so I did that in the session callback.

The example below shows taking information from the token and passing that along to the session.

// pages/api/auth/[...nextauth].ts
...
callbacks: {
        async session({ session, token }: any) {
            session.accessToken = token.accessToken;
            session.idToken = token.idToken;
            session.oktaId = token.oktaId;
            return session;
        }
    }
...

NextAuth.js Session Callback Documentation

Closing

When adding authentication to your Next.js app with NextAuth.js it’s likely you will need to use the callback feature if you want to go beyond the most basic implementation. This was definitely the most confusing and difficult part for me but I hope the code samples are useful in your auth implementation!

To learn more check the Callback Docs page provided by NextAuth.js or reach out to me and I’d love to learn more about your project and help out. If you need help getting your initial setup of NextAuth.js working read my previous blog: Adding Authentication to Nextjs with NextAuth.js and Okta.

What and Why: React Server Components in Next.js 13

Thomas Desmond — Thu, 10 Nov 2022 18:03:40 +0000

React Server Components are now fully supported in Next.js. Next.js 13 was recently released and React Server Components move out of experimental into full support. I would go beyond saying Next.js supports them to Next.js is heavily pushing for the use of React Server Components.

Next.js 13 introduced app directory architecture which is an entirely new way to architect your Next.js applications with React Server Components in mind. The default for components built under the app directory are React Server Components, you must explicitly add use client if you want to build a client-side component.

It’s okay if you have never heard of React Server Components. They only came into existence in December 2020 and so far are not widely used. Let’s look into React Server Components and why the Next.js team wants you to use them by default.

What is a React Server Component?

A React Server Component is a component that renders on the server. React Server Components leverage the server's power to provide a more predictable and performant experience for your visitors.

The most common use case for a Server Component would be to fetch data and render your component based on that data all on the server.

Things that you’ll want to consider putting in a Server Component would be:

Fetching data (take advantage of the server's super speedy connection)
Accessing backend resources or filesystem
Components with large dependencies that do not need client-side interactivity

💡 React Server Components cannot include any client-side interactivity, this means your app will most likely contain a mix of server components and client-side components. This adds complexity as you’ll need to think ahead of how you want to best distribute components, but the goal is to move as much to the server where things are predictable and more performant.

Common examples of client-side only calls: useState, useEffect, onClick

Why do you want React Server Components?

The number 1 reason is Server Components contribute zero to the overall bundle size of your application. This means smaller download sizes for visitors, leading to your page becoming available faster.

This benefit can be extremely helpful if you have packages you need to use but do not need them client side. Keeping those dependencies completely server-side means reduced downloads for the client. For example, I use an npm package for this blog to convert my .mdx files to HTML. That could be a completely server-side process, removing that package from the bundle downloaded by the client.

As mentioned above, another big benefit is that your code is running on a powerful server, hopefully, closer to your data as well. Pushing compute to the server can make a big difference for your visitors on a mobile device.

How to get started with React Server Components?

If you want to build with React Server Components upgrade to Next.js 13 or use create-next-app to start a new app and build with the new app/ based architecture.

Components built with the new Next.js 13 app folder-based architecture will be React Server Components by default. The new architecture is still in beta but I expect it to become recommended practice soon. The goal of this new architecture is to reduce the amount of JavaScript sent to the client.

Don’t worry though the original pages/ based architecture that has been used in all prior versions of Next.js is still supported in version 13 as well. You can incrementally adopt the new architecture.

Next.js Authentication with Okta and NextAuth.js 4.0

Thomas Desmond — Wed, 19 Oct 2022 21:19:56 +0000

Looking to add authentication to your Next.js application? Considering Okta as your login provider? You have come to the right place! This article covers adding authentication to your Next.js application with NextAuth.js and using Okta as a login provider. All with TypeScript in mind along the way.

If you don’t want to use Okta that’s fine, skip to section 3 to see how to use NextAuth.js with any properly configured provider.

Here’s the GitHub repository where I have all the code mentioned in this article. Also, I think it’s important to note the package versions that this article has been tested against: next 12.3.0, next-auth 4.13.0, react 18.2.0

1. Create A Brand New Next.js App and Install NextAuth.js

npx create-next-app --ts

This creates a brand new Next.js application for us and the --ts means the starter app will be initialized with TypeScript. Go through the options, name your app, and you’ll have a brand new Next.js app with TypeScript!

Change directories into your new app and the first thing you’ll do is install NextAuth.js. The package is called next-auth.

npm i next-auth@4.13.0

I’ve put the explicit @4.13.0 because that’s the latest version that I have tested for this article. I assume any 4.0 version will work but I wanted you to be aware of what I have explicitly tested against.

❓ What is NextAuth.js? NextAuth.js is an open-source authentication solution created by the community that loves Next.js. It’s built with Next.js in mind the whole way for static, server side, and API route authentication. Check out the NextAuth.js introduction to learn more.

2. Create an OIDC Application in Okta

You need an OIDC application in Okta which you will authenticate against. I did this process using the Okta CLI but it can also be done by logging into Okta.com and creating an app there.

Install the Okta CLI
1. Easily done with Chocolatey choco install okta
If you DO NOT have an account run okta register. If you DO have an account okta login
Create your app with okta apps create
1. Take the default app name or rename if you would like
2. Choose the Web option for the Type of Application
3. Choose Other for the Framework of Application
4. Redirect URI: http://localhost:3000/api/auth/callback/okta
5. Logout Redirect URI: http://localhost:3000
You just created your Okta app in the CLI! You will see that a .okta.env file was created in your Next.js application. This holds the important environment files that you’ll need.

❗ Add .okta.env to your .gitignore file. The .okta.env file contains sensitive information that should not be in source control.

// .okta.env created by CLI
export OKTA_OAUTH2_ISSUER="URL of your Okta Account"
export OKTA_OAUTH2_CLIENT_ID="Client ID - Preferred not to be shared"
export OKTA_OAUTH2_CLIENT_SECRET="Client Secret - Definitely do not share"

3. Initial NextAuth.js setup & configuration

Now it’s time to get into using the next-auth package you installed and set up Okta as an authentication provider. With NextAuth.js it’s a similar workflow for adding additional providers, but I’ll be sticking with Okta for this example.

1 Create a .env.local file at the root of your project. This is what the Next.js application will access to get any environment variables. Copy everything over from the .okta.env into your new .env.local but remove the export from in front of the variables.

❗ Make sure your .env.local does not go into source control now that you have put sensative information into it. If you created your app with npx create next app --ts it should already be in your .gitignore.

// .env.local
OKTA_OAUTH2_CLIENT_ID=asdfasdf
OKTA_OAUTH2_CLIENT_SECRET=asdfasdfasdfasdf
OKTA_OAUTH2_ISSUER=https://dev-27410971.okta.com/oauth2/default

2 Two more variables need to be added to .env.local: NEXTAUTH_URL and SECRET.
1. NEXTAUTH_URL will be http://localhost:3000 for development
2. SECRET is generated by you. I used https://acte.ltd/utils/randomkeygen and copied the Encryption Key 256 to use for my value.

// .env.local
OKTA_OAUTH2_CLIENT_ID=asdfasdf
OKTA_OAUTH2_CLIENT_SECRET=asdfasdfasdfasdf
OKTA_OAUTH2_ISSUER=https://dev-27410971.okta.com/oauth2/default
NEXTAUTH_URL=http://localhost:3000
SECRET=123456asdf

3 Now create a [...nextauth].ts file under the pages/api folder of your application. This is a special file used by NextAuth.js, that handles the sign-in and sign-out process for your Next.js application. Paste the following code into your file.

//pages/api/[...nextauth].ts
import NextAuth from 'next-auth'
import Okta from 'next-auth/providers/okta'

export const authOptions = {
    // Configure one or more authentication providers
    providers: [
        Okta({
            clientId: process.env.OKTA_OAUTH2_CLIENT_ID as string,
            clientSecret: process.env.OKTA_OAUTH2_CLIENT_SECRET as string,
            issuer: process.env.OKTA_OAUTH2_ISSUER as string,
        }),
    ],
    secret: process.env.SECRET as string
}

export default NextAuth(authOptions)

4 Now we move to the pages/_app.tsx file. We need to add a Provider that wraps our entire application here so that the NextAuth.js session data can be shared between components and pages.

import '../styles/globals.css'
import type { AppProps } from 'next/app'
import { SessionProvider } from "next-auth/react"
import { Session } from 'next-auth'

export default function App({
  Component,
  pageProps: { session, ...pageProps },
}: AppProps<{ session: Session; }>) {
  return (
    <>
      <SessionProvider session={session}>
        <Component {...pageProps} />
      </SessionProvider>
    </>
  );
}

At this point, you have authentication setup. What is covered next is the way to use the next-auth package you installed and set up. This will work if you have set up Okta as I showed above or if you have properly set up one or more of the many other providers you can use with NextAuth.js.

4. Adding Authentication to Pages

Now it’s time to look at actually putting content behind authentication in your Next.js pages and API endpoints. Keep in mind this article makes no attempt at having a pretty user interface (UI). The focus is on authentication and I did not want to have any added complexity.

In this section, you will see three authentication implementation patterns:

Client Side Authentication
Server Side Authentication
Next.js API Route Authentication

Client Side Authentication

Authentication on the client side is not usually the best approach. The reason for this is that the data is sent to the client then authentication happens after. The visitor will not technically see any data on the page that they are not allowed to see but has the ability to access it if they really wanted to. Maybe you don’t have super sensitive that allows for client-side authentication.

Below is a code sample for executing client-side authentication for a Next.js page. It has a loading state that displays while the authentication status is being checked and then displayed the proper text and signIn or signOut button respectively.

// client-auth.tsx
import { signIn, signOut, useSession } from "next-auth/react"

export default function ClientSideAuth() {
    const { data: session, status } = useSession()

    if(status === 'loading'){
        return (
            <>
                Loading...
            </>
        ) 
    }

    if (session) {
        return (
            <>
                You have logged in <button onClick={() => signOut()}>Sign out</button>
            </>
        )
    }
    return (
        <>
            Not Logged In <button onClick={() => signIn()}>Sign in</button>
        </>
    )
}

Notice the awesome signIn and signOut methods passed into the onClick handlers. These are provided by the next-auth/react package. These buttons will send users to the api/auth/[...nextauth].ts route you created and automatically handle the sign in and sign out process for you. It’s that easy to get login work in your application.

💡Only using one login provider? Consider modifying the code to use signIn('okta') and it will bring users directly to Okta’s login portal. This works for other providers as well, example signIn('github')

Server Side Authentication

Performing authentication server side is preferred. This is because the route will be pre-rendered by the server and only the appropriate content will make it to the client. If authenticated only that portion of the content is sent to the client and the same goes for unauthenticated content.

The below code is a Next.js page with getServerSideProps indicating the page is using server side rendering (SSR). It may look scary to use unstable_getServerSession call but that is the recommended method as of now. It is more performant than previous implementations provided NextAuth.js.

Server Side Redirect If Not Authorized

// server-auth.tsx
import { unstable_getServerSession } from "next-auth/next"
import { authOptions } from "./api/auth/[...nextauth]"

export async function getServerSideProps(context: any) {
    const session = await unstable_getServerSession(
        context.req, context.res, authOptions)

    if (session) {
        return {
            props: { username: session?.user?.name }
        }
    }
    return {
        redirect: { destination: "/", permanent: false }
    }
}

export default function ServerSideAuth(username: string) {
    return (
        <>
            <h1>Protected Page</h1>
            <p>You can view this page because you are signed in as {username}</p>
        </>
    )
}

The above code checks the session within getServerSideProps to see if the user is authenticated. If they are we return the user's name and if they are not they get redirected to the homepage. For this app I do not have a dedicated login page, but if your application has a login page that would be a great place to send people that are not authorized.

💡 What does the permanent value mean in the redirect? Permanent can be one of two values true or false. If true the redirect will use the 308 status code which instructs clients/search engines to cache the redirect forever, if false will use the 307 status code which is temporary and is not cached.

Next.js API Route Authentication

If you need to add authentication to a Next.js API route you can use the same unstable_getServerSession that was used above in server side authentication.

// api/api-auth.ts
import { NextApiRequest, NextApiResponse } from "next";
import { unstable_getServerSession } from "next-auth/next";
import { authOptions } from "./auth/[...nextauth]";

export default async function handler(
    req: NextApiRequest,
    res: NextApiResponse
) {
    const session = await unstable_getServerSession(req, res, authOptions)
    if (session) {
        res.send({
            content:
                "This is protected content. You can access this content because you are signed in.",
        })
    } else {
        res.send({
            error: "You must be signed in to view the protected content on this page.",
        })
    }
}

If authorized you send them the protected content, otherwise the code sends back and error to the user making the request.

Summary

With NextAuth.js authentication in Next.js become much simpler. With a little setup, you can easily add Okta support to your application, and after that initial setup, it’s very easy to add additional providers like GitHub, Google, or even bring in your own database.

You now have all the knowledge you need now to create a Next.js application that has content protected by an authentication layer connected to Okta. Remember server side authentication is the safer method for ensuring visitors only see the content they are supposed to.

Next-auth is a powerful library and I encourage you to explore its more advanced capabilities of it so you can be as informed as possible when it comes to authentication and the security of your application.

Here is the GitHub Repository with all the code from this article.

🚨Need help? Reach out to me on my Bio page or send me a message on Twitter. I’d love to see what you are building and help where I can.

Introduction to Frontend Development with XM Cloud Hybrid Headless CMS

Thomas Desmond — Mon, 19 Sep 2022 23:38:51 +0000

Thinking about building a frontend with Sitecore Experience Manager Cloud (XM Cloud), Sitecore’s latest headless CMS offering? Read on to learn about the frontend developer experience for XM Cloud. Learn how Sitecore takes a Hybrid Headless approach to CMS’s to differentiate itself from competitors, giving content authors the functionality they need and you the developer, the tools to support frontend development.

This article explains what XM Cloud is and provides two common workflows for frontend developers, one simple and one more advanced. You’ll also learn about Sitecore Headless Services, a framework for seamless frontend development.

Who is this for:

I wrote this article for developers who are currently or plan to develop a frontend against the headless CMS XM Cloud. This article will stay high-level sharing insights into the frontend developer experience and the role Sitecore Headless Services plays in the development process. You’ll find references to a lot of additional resources for topics you may want to take a deep dive into. If you are experienced in Sitecore XM or Headless Services this article may not be for you.

What is Sitecore Experience Manager Cloud?

First off, Sitecore Experience Manager Cloud will be referred to as simply XM Cloud going forward. Good, because that’s a lot shorter and easier to read.

So what is XM Cloud? XM Cloud is Sitecore’s headless content management system (CMS). XM Cloud bundles Experience Manager, the Pages editor, Sitecore Experience Accelerator (SXA), Headless Services, and Experience Edge. It’s capable of creating omnichannel experiences, but the prominent focus is on web apps.

I just listed a lot of different products and services that make up XM Cloud; it can be overwhelming to attempt to learn them all at once. While Pages and SXA are important to the XM Cloud product this article is going to focus on Experience Manager, Headless Services, and other important aspects of the frontend developer experience.

The Sitecore Developer Portal has a great XM Cloud Introduction resource if you want more developer-focused content about XM Cloud. Up next you will learn about the developer experience when working with XM Cloud.

Developer Experience

Development Mindset Shift for Content Management Systems

Keeping the content author in mind

If you have never built a frontend where all the content was hosted in a CMS, then you will need to be prepared for a mindset shift when it comes to your development process.

Working with XM Cloud or any CMS requires a mindset shift where you need to continuously think about the content author that will be managing the content. You as the developer want to make the content author's life as easy as possible, this may development is a little harder for you.

❔ What’s a content author?
Sitecore users who manage content are called Content Authors. Sitecore provides content authors the ability to create pages, add components to pages, edit content displayed by the components, and define personalization rules.

With XM Cloud the content author’s will have access to a page designing tool, appropriately named Pages. This allows the content authors to maintain and update content through a simple WYSISYG editor. It will be up to you as the frontend developer to build reusable components that content authors can then utilize inside Pages.

This also means that no content should be hardcoded into your frontend code. Content authors will want to update text, images, icons, and more all within XM Cloud and your frontend will need to be able to handle these changes. Don’t worry, Sitecore’s Headless Services helps make this easier and we’ll cover that more later.

Your frontend will need to be flexible to handle whatever content and layout the content authors throw at you. But this is easy if you follow a component-driven design way of building your application.

Now let’s take a look at two workflows that frontend developers will run into when working with XM Cloud.

Simple Workflow: Building Your Frontend Against a Deployed XM Cloud

This first workflow is for developers that want to work strictly on the frontend of their app. For this, you will develop against a deployed instance of XM Cloud. Your XM Cloud instance publishes all content out to Experience Edge and you develop against that.

The only two pre-requisites for this are having Node.js and the .NET 6.0 SDK installed, both of these are available for Windows, Mac, and Linux! You need the .NET SDK to use the Sitecore CLI and Node to act as your rendering host to render your frontend locally. With minimal setup, you can be working on your local machine, with any operating system, building and maintaining your frontend.

💡 This workflow assumes that the deployed XM Cloud instance is all set up and contains the data you need to make your beautiful frontend. You will probably want to get access to the XM Cloud environment still so you can take a peek at what data you are expected to have available to you.

Advanced Model: Workflow with Containers Locally

A common scenario when working with XM Cloud is that you will actually be developing against XM Cloud locally on your machine. You will use the Sitecore CLI and Docker to replicate the XM Cloud environment locally.

💡 This does mean you will need a Windows machine, unlike the workflow above that could work on any OS.

In this local containerized scenario, you can build out your frontend against the locally running XM Cloud. Also if you take this approach I would expect you to be or become familiar with some of the features of XM, branching out from your frontend technology.

I’d recommend becoming familiar with the Content Editor and Experience Editor. As a frontend developer, you do not need to know intricate details of how XM works, but a familiarity to navigate the Content Editor and Experience Editor is helpful. This will make your life easier when you need to look for what data you should be expecting on the frontend.

Once you are happy with the changes you made in your local containerized environment, you can push those to GitHub, this is the preferred source control currently because of its direct integration with the XM Cloud Deploy App. At this point, the deploy app takes over and handles the deployment of the code to your XM environment.

Simple vs Advanced Workflow Which to Choose?

Why would you need to use the advanced model? The advanced workflow allows you to make changes within XM Cloud, essentially create/modify/update Sitecore items. With the simple workflow you can only work against what has already been published to Edge from a deployed XM Cloud instance.

If all you need to do is build your frontend the simple workflow is perfect for you. If you need to make changes within XM Cloud the advanced workflow will probably be the way to go.

Building your Frontend against XM Cloud

Now that you know more about the developer experience of building with XM Cloud what will you be building your frontend with? What’s the recommended frontend framework? If XM Cloud is headless can’t you build with any frontend? Let’s jump into answering these questions now.

A little background first. A typical Headless CMS separates content management from content delivery. The frontend retrieves data from the CMS via APIs. This data is then displayed via a layout created by the frontend developer (that’s you!).

XM Cloud takes a Hybrid Headless approach because not only does the CMS contain content, but it also contains information on where the content should be in the layout. With XM Cloud content authors have the power to create content AND move content around in the layout.

This is possible because you will build modular components that do not care where they are on the page. All components are self-contained and independent of one another. This is how you would want your frontend architecture anyway even if you were not using a hybrid headless CMS.

The hybrid headless approach to CMS’s is one of the biggest differentiators between XM Cloud and other Headless CMS. XM Cloud gives content authors the power to move content pieces anywhere they want on the page and it’s up to you the developer to be able to handle this.

Sitecore Headless Services

That’s where Sitecore Headless Services comes in!

Headless Services help you develop your frontend against XM Cloud as a backend. Essentially making it easier to handle Sitecore’s approach of allowing content authors to have control of where content is displayed.

Sitecore Headless Services has been built to support the most popular JavaScript frontend frameworks as well as .Net. However, for XM Cloud the recommended frontend framework is Next.js because of its ability to do static site generation (SSG) and server-side rendering (SSR) easily on a page-by-page basis. Yes, you can choose whatever frontend framework you like but for the best support and easiest integrations, Next.js is recommended.

The above image depicts how Sitecore Headless Services sits between XM Cloud and your frontend application. You then use the JSS SDK, specifically the Next.js one, to support your frontend development. The combination of Headless Services with the frontend SDK helps you develop more effectively against XM Cloud.

❔ Is Sitecore Headless Services Required?

Technically no, but highly recommended. With the release of Experience Edge for XM, you can now query your XM Cloud content via GraphQL from any frontend, web, mobile, watch, tv, or toaster.

Headless Services has come a long way to help you develop effectively and efficiently again XM Cloud. It is my recommendation that you make a strong effort to use Headless Services with Next.js in your XM Cloud implementation.

There is quite a bit more detail to Headless Services that I do not want to get into with this article. I hope to make or share more hands-on in-depth tutorials to help you become a proficient frontend developer jumping into the Sitecore XM Cloud world.

Check out the Headless Services page on the developer portal to learn more.

Summary

XM Cloud is an exciting release for Sitecore. It brings the popular hybrid headless Experience Manger to the cloud. Lots of work has been put in to make the local containerized workflow as seamless as possible, and once you have XM Cloud deployed you can take advantage of building directly against XM cloud with no containers. Headless Services is continuously improving to meet the needs of frontend developers building against XM Cloud.

There is still plenty to learn to get the most out of XM Cloud but I hope this introduction was helpful.

If you have made it this far congratulations! If this content was helpful to you please share it with your peers. If not please reach out to me on Twitter @ThomasJDesmond, Sitecore Slack, or the contact form on my Bio page and let me know what this article needs to be more valuable. I appreciate the feedback!

Further XM Cloud Learning Content

XM Cloud Resources

XM Cloud Introduction - Sitecore Developer Portal

XM Cloud Code Sample - Powers Sitecore MVP site and all SUGCON event sites

Headless Services Resources

Headless Service - Sitecore Developer Portal

Sitecore Headless Development - Sitecore Documentation
Headless and JSS - YouTube Playlist

👋 Have a specific question about XM Cloud or other Sitecore products? Consider joining the Sitecore Slack Channel or asking questions on Sitecore Stack Exchange.

Forem: Thomas Desmond

Cloudflare Pages and Next.js: I'm Not Recommending It

Next.js Host Check App

My Experience with Next.js on Cloudflare Pages

Next.js Feature Support in Cloudflare Pages

Conclusion

How Well Does Azure Static Web Apps (SWA) Support Next.js? | Pages Architecture

Next.js Application Overview

How I Deployed the Next.js Application

Next.js Support in Azure Static Web Apps

How to Test Hosting Providers Yourself

Exploring Every Feature in Next.js and Testing Hosting Providers

The Project Overview

Testing and Automation

Future Prospects

Join Me on this Journey

Stay Tuned for More

Vercel and Netlify's Convenience Layer: Simplify Your Frontend Workflow

What is the Convenience Layer?

Development Features

Review Feature

Deployment Features

Production Features

Scaling Features

Scenario Taking Advantage of the Convenience Layer

Turn This Complicated Workflow:

Into Something Much Simpler with Netlify:

Why Choose Vercel and Netlify?

Beyond Vercel: Hosting Alternatives for Next

Hosting Options

Hosting Next.js on Netlify

Next.js with AWS Amplify

Microsoft Azure Static Web Apps

Dedicated Node.js Hosting & Self-Hosting Next.js

Conclusion

Next.js App Directory Architecture First Impressions

1. Documentation

2. Server Components vs. Client Components

3. Package Support

4. Migrate now or later?

Client Components and use client in Next.js App Directory

Declaring a Client Component

What does use client do in Next.js?

How is a Client Component rendered?

Pre-rendering vs. Hydration in Next.js

Does having use client mean I’m using Next.js 13 wrong?

Closing

3 Big Changes in The New Next.js App Folder Architecture

The Architecture

Component Rendering

Data Fetching

Routing

Closing

Accessing JWT and Session Data in NextAuth.js with Callbacks (Okta Example)

Callbacks in NextAuth.js

The JSON Web Token (JWT) Callback

Session Callback Example

Closing

What and Why: React Server Components in Next.js 13

What is a React Server Component?

Why do you want React Server Components?

How to get started with React Server Components?

Next.js Authentication with Okta and NextAuth.js 4.0

1. Create A Brand New Next.js App and Install NextAuth.js

2. Create an OIDC Application in Okta

3. Initial NextAuth.js setup & configuration

4. Adding Authentication to Pages

Client Side Authentication

Server Side Authentication

Next.js API Route Authentication

Summary

Introduction to Frontend Development with XM Cloud Hybrid Headless CMS

Who is this for:

What is Sitecore Experience Manager Cloud?

Developer Experience

Development Mindset Shift for Content Management Systems

Simple Workflow: Building Your Frontend Against a Deployed XM Cloud

Advanced Model: Workflow with Containers Locally

Simple vs Advanced Workflow Which to Choose?

Building your Frontend against XM Cloud

What does `use client` do in Next.js?

Does having `use client` mean I’m using Next.js 13 wrong?