Get comfy with new terminology and technology

This lesson covers key terminology and mental models in transitioning from a legacy monolith or a headless CMS to a Content Operating System like Sanity.

Before starting the migration process, it's essential to understand some critical technical terminology involved with a re-platforming project. Note that the following definitions are written from our point of view and understanding of what makes Sanity different. Adopting this point of view can be helpful when onboarding your team or getting buy-in for the re-platforming project.

Content Operating System: You might have been introduced to Sanity as a "Content Management System (CMS)," "Composeable Content Platform," or "Headless CMS." Keen readers might notice that we chose to refer to Sanity as a "Content Operating System." At Sanity, we use the latter because we understand the platform as something broader regarding the problems it solves compared to most (headless) CMSes on the market. Adopting this term also allows your team to think more broadly and deeply about how you accommodate content workflows for your team: It's so much more than just publishing and distributing content to a website. Content moves through a life cycle and between systems.

Monolithic Content Management System (CMS): A CMS, especially one established in the early 2000s to mid-2010s, where both content publishing and website rendering are done using the same system with a built-in templating engine. They often require developers to be proficient in a backend programming language (like PHP, .NET, or Java) and front-end languages like HTML, CSS, and JavaScript. The content management affordances are often constrained to web publishing and a single website property.

Headless CMS: A headless CMS decouples the content repository (the "body") from the presentation layer (the "head"). This allows the content to be delivered to any front-end or device over APIs. In many ways, you can think of Sanity Studio as the "Headless CMS" component in your new Content Operating System stack, fulfilling many of the same user tasks. However, unlike most Headless CMSes, it's designed to be configured and customized to fit exactly how you want to work.

Compared to "monolithic" architectures, a single server runs an application responsible for storing, enabling editing, and rendering your content.

API-first / API-driven: An Application Programming Interface (API) allows developers to integrate content across systems. CMSes often offer APIs, but that doesn’t necessarily mean that the systems are designed with API use in mind. To be API-first/API-driven, a system is built with the assumption that content will be accessed through an API, and it needs to be interoperable in different systems.

This means that content can be created, managed, and delivered entirely via APIs, enabling developers to retrieve content in the structure and format they need. Sanity is built as an API-first platform.

JAMstack/Jamstack stands for JavaScript, APIs, and Markup. It's an architecture designed to make the web faster, more secure, and easier to scale. The initial "headless" movement was regularly coupled with references to the Jamstack; however, the term no longer carries real active meaning and has been phased out by vendors that first popularized it.

MACH stands for “microservices, API-first, cloud-native SaaS, headless” and is mainly used by members of the MACH Alliance, a group of companies and vendors that have paid to be certified and members. While Sanity is not a member of the MACH Alliance, it is based around microservices, API-first, cloud-native, and headless and built on the goal and philosophy of being "composable."

Static Site Generators (SSGs): Refers to a class of front end frameworks that exploded in popularity at the beginning of the headless movement (like Gatsby, VuePress, and Eleventy). Made popular in response to server environments, which were slow, expensive, unreliable, and insecure. SSGs prioritized the speed of page loading and security over all else.

However, most modern web "pages" are actually web "applications" and so require more dynamic interactions than a "static file" can typically provide. Server environments are now cheaper, simpler, and faster than ever before.

Most modern front-end frameworks now prioritize server-side-rendered pages, emphasizing caching and globally distributed assets and servers for speed. You will see fewer references to SSGs in modern website development.

Single Page Applications (SPAs) are web applications that entirely run in the browser with content and data fetched over APIs. They became popular with the introduction of front-end libraries like Angular, React, and Vue in the mid-2010s, making creating highly dynamic user experiences easier. The trade-off was that they also would require a lot of JavaScript to load and often broke with expected browser behavior (like how the back button works).

Modern web application frameworks like Next.js, Nuxt.js, Remix, and Astro allow developers to specify what should run on the server or in the client, depending on a route or a component.

There are several critical benefits to migrating to an API-first Content Operating System like Sanity – many of these apply to headless CMSes as well:

API-first architectures reduce the surface area for potential attacks by decoupling the content repository from the presentation layer. The content is delivered to end-users via read-only APIs, making compromising much harder.

With Sanity, all content operations are available via APIs. This allows developers to retrieve and update content in the format and structure they need and integrate it with other systems and applications.

Since content is decoupled from presentation, multiple teams can build distribution channels (website, mobile app, digital displays, etc.) that pull from the same central content repository. This allows for greater flexibility and faster development.

Going API-first opens up many options for front-end tooling and frameworks. Developers can choose the best tools for the job rather than being locked into a monolithic system.

While there are many benefits to migrating to a Content Operating System, there are also some potential challenges. Being aware of and having a plan for these going into a re-platforming project will help you onboard your team, anticipate concerns from stakeholders, and ensure that the re-platforming is successful.

API-driven systems typically require different technical knowledge to set up and maintain than traditional website-centric CMSes. With Sanity specifically, you might need to learn GROQ and some specific ways you work with content models. On the positive side, it usually allows your developers to work with one programming language (JavaScript/TypeScript). Customizing the editorial experience will build on the same technologies and mental models as building your front ends, which means less context switching and more productivity.

Your content team will likely also need additional training or support from your developers. Since the content operations experience you're creating will be unique to your business, which is primarily a plus, it does make it harder for us to provide learning materials on the specifics of how content operations look in your business.

Web-centric CMSes have built-in website-specific features like redirects, link checkers, and SEO tools. With an API-first CMS, some of this functionality is moved to the front-end layer, and you may need to build it yourself or integrate third-party services.

Structuring your content to model what it is rather than what it looks like on a web page unlocks many possibilities beyond your website. Authoring structured content has a longer tail of benefits that will outlast your website's current design.

Content creators may feel less confident working in a Content Operating System if they're used to the visual, drag-and-drop interfaces of traditional CMSes. Providing training and establishing transparent workflows is essential to maintain author confidence.

Not only should your content team be shown how the Sanity Studio works, but also the network benefits of thinking about your content beyond just your website.

Giving your team the ability to preview draft content in the front end(s) can go a long way to ensuring your content team's confidence to press publish.

Migrating to headless means carefully evaluating and selecting your content architecture, asset storage, personalization engine, email delivery, and other architecture components. This requires research and planning to ensure that all the pieces work well together.

The benefit to API-driven architecture is that should you ever need to migrate off any one part of the stack, it should be a much smaller project than your current one to migrate from a monolith.

When migrating to an API-driven architecture, you'll need to select the right components to power your stack. Here are some critical considerations for each piece:

Your content architecture is the heart of your content operations. Look for a system with:

• A flexible content modeling system to structure your content
• Powerful APIs to receive and deliver content from and to any channel
• Easy-to-use, configurable authoring interfaces for your content team
• Extensibility to customize the CMS to your needs

Fortunately, Sanity covers all of this and more!

Sanity stores all your assets into the same dataset as your text content. However, more dedicated providers might be preferable in certain instances.

If you have a massive image catalog, integrate your DAM with Sanity using custom asset sources:

A dedicated provider will likely offer more options for applications that rely on fast delivery of large amounts of video content. Fortunately, Mux provides a great plugin for integrating videos hosted on its platform.

If your existing solution allows you to create forms, store submissions, and send emails, you must recreate this in Sanity or leverage a dedicated server.

The primary role of configuring schema types in Sanity Studio is to create editing forms for content in Sanity Studio—not forms for your front end(s).

Since you can model anything, you are free to model forms, too! Your front end can write submissions to the dataset using Sanity Client. You can also send notifications using GROQ-powered webhooks.

Serving different content to user segments and tracking the results is possible in a headless environment. Still, it will require integrating a service with the context of both your back and front end.

Some integrations are available for Sanity, and most personalization providers are API-driven and, thus, can be integrated.

Choosing the "right" front-end is a question without one correct answer. Trade-offs depend on your team's expertise, comfort level with different frameworks, and more.

Sanity content can be integrated with any front end technology on any hosting platform. So, this decision mostly has to do with the preferences of your team and your strategy when hiring front-end development talent.

For JavaScript frameworks, Next.js is presently the most popular choice and is well-supported through the next-sanity toolkit.

Alternative server-rendered JavaScript frameworks include Remix / React Router. On top of this foundation, the Hydrogen framework is designed to work with a tight integration with Shopify for e-commerce sites.

If you are building a mobile application, successful Sanity deployments run on Expo for React Native or Flutter for Android.

You may already have a front-end that consumes content from an API. If so, you can restructure your content in Sanity and create an API that serves content in the same "shape" your front-end expects.

GROQ is the primary way to query content from Sanity and can reshape data as it is queried, but you can also use Sanity’s GraphQL API to integrate content into your front end.

With these challenges in mind, let's move into what it means to re-model your content in a re-platforming project.