Loaders: Enhanced content fetching for Visual Editing

Loaders enable enhanced content fetching capabilities for Visual Editing. They provide a unified way to load content from your Sanity Content Lake into your front-end application, seamlessly supporting both server-side rendering (SSR) and client-side rendering (CSR) for GROQ and GraphQL.

This article provides a high-level overview and introduction to Loaders. It is valuable reading for those who want to understand better how they work and why they are beneficial.

You can head over here for implementation guides and links to tooling:

With Loaders, you can integrate Visual Editing functionality into your application, allowing content editors to make real-time updates directly from the Sanity Studio. Loaders handle the complexities of fetching and synchronizing data between the Content Lake and your application, ensuring a smooth editing experience.

If you have used Sanity before, you can think of Loaders like an enhanced client that reduce the complexity that goes into accommodating a full Visual Editing experience.

Key benefits of using Loaders include:

• Simplified data fetching: Loaders provide a consistent API for fetching content, regardless of whether you're using server- or client-side rendering (or both)
• Real-time updates: Thanks to Loaders' live-updating capabilities, changes made in Sanity Studio are instantly reflected in your application.
• Seamless Visual Editing integration: Loaders enable the rendering of interactive overlays in your application, allowing editors to click on content and edit it directly in the Studio.
• Makes your front end compatible with future improvements for Sanity’s Visual Editing suite.

Loaders are primarily implemented using a framework-specific toolkit (like next-sanity or the Sanity module for Nuxt). They support both GraphQL and GROQ, and for cases where there is no framework-specific tooling or you are using no framework, you can also rely on the core Loader library.

Loaders and the Visual Editing tooling are designed for progressive disclosure. That means you can start by adding Loaders only for fetching content server-side, and then, when the need arises, you can add a client-side loader to accommodate a faster and richer Visual Editing experience.

// Example of server- and client-side loaders for Visual Editing in a Remix application
// ./app/routes/_index.tsx

import { useLoaderData } from "@remix-run/react";
import Posts from "~/components/Posts";
import { useQuery } from "~/sanity/loader";
import { loadQuery } from "~/sanity/loader.server";
import { POSTS_QUERY } from "~/sanity/queries";

export const loader = async () => {
  // The server-side loader 👇
  const initial = await loadQuery(POSTS_QUERY);

  return { initial, query: POSTS_QUERY, params: {} };
};

export default function Index() {
  const { initial, query, params } = useLoaderData<typeof loader>();
  // The client-side loader 👇
  const { data, loading } = useQuery<typeof initial.data>(query, params, {
    initial,
  });

  // `data` should contain the initial data from the loader
  // `loading` will only be true when Visual Editing is enabled
  if (loading && !data) {
    return <div>Loading preview...</div>;
  }

  return data ? <Posts posts={data} /> : null;
}

For Loaders to work with Visual Editing, there are a couple of requirements to how your front end application:

Minimum requirements

• Server-side rendering and route and/or component-based data loading
• A server-side token with read permissions
• A way to pass the toggle for authenticated and enabled preview mode to the server

Recommended requirements

• A framework that supports client-side rehydration, like React, Vue, or Svelte
• A framework that has a built-in draft/preview mode, like Next.js or Nuxt, or a way to pass

What about Visual Editing for static site generators (SSGs)?

While static site generators can make it simple to build websites, they are not well-suited for providing a Visual Editing experience for content teams. Static site generators pre-render pages at build time, meaning any content changes require a full or partial site rebuild. This usually doesn't scale well as the site grows and does not provide the real-time editing experience that Loaders enable.

However, some frameworks, like Astro, also support server-side rendering. Suppose you wish to use static site generation for your production builds. In that case, a strategy can be to set up a secondary deployment for previews that uses server-side rendering with Loaders.

To provide the best Visual Editing experience for your content teams, we recommend using a framework that supports server-side rendering and client-side hydration, such as Next.js, Remix, Nuxt.js, or SvelteKit. These frameworks allow you to leverage the full power of Loaders, including real-time updates and interactive editing overlays.

For new (greenfield) projects, we recommend implementing Loaders from the start and setting up both server- and client-side loaders.

If you use GROQ, we also recommend collating and exporting queries in the same file, making query reuse easier across the server-side and client-side loaders.

For existing (brownfield) projects, you can progressively adopt Loaders to enable Visual Editing capabilities. Start by implementing server-side Loaders to fetch content from the Content Lake during server-side rendering. This lets you render draft content in preview mode without requiring client-side fetching.

When integrating Loaders into an existing project, consider the following high-level steps:

1. Identify the framework-specific resources for the front end you are using so you can leverage those tools and procedures.
2. Configure the Presentation Tool in the Studio with the URL to your front end.
3. Configure a server-side loader and start testing on a specific route, for example, if you have a blog or news section. At this point, you can choose whether to come back later to add client-side loaders for faster and more capable preview experiences or do it later, depending on your project’s needs.
4. Set up the preview toggling mechanics (which can differ depending on your framework) and conditionally load the VisualEditing component.
5. Stega-strings should automatically add overlays to most of your content, but you might need to add support for specific components/elements using the encodeDataAttribute function.
6. Test locally how your route deals with preview data and set up guards (or default values) against null values, and so on.
7. When you are confident it works, let your content team test the experience and get comfortable before you roll it out in production.
8. After testing it in production, you can individually enable a preview for the rest of your routes. Usually, content creators and teams might have insight into what to prioritize.