Presentation Tool Resolver

Relevant source files

The following files were used as context for generating this wiki page:

• sanity/plugins/resolve.ts
• sanity.config.ts
• sanity/lib/api.ts
• app/studio/[[...index]]/page.tsx
• app/(personal)/layout.tsx
• sanity/lib/client.ts

The Presentation Tool Resolver is a critical configuration component within the Sanity Studio that enables visual editing and real-time content previews. It maps Sanity documents to their corresponding frontend routes, allowing editors to click on content in the preview pane to jump to the exact document in the Studio, and vice versa.

Within this project, the resolver acts as the bridge between the Sanity Studio (hosted at /studio) and the Next.js frontend application. It defines how different document types—such as projects and pages—translate into URL paths that the Presentation tool can use to display live previews.

Sources: sanity.config.ts:54-57, sanity/plugins/resolve.ts:1-5, sanity/lib/api.ts:35

Architectural Integration

The resolver is implemented as a set of configurations passed to the presentationTool plugin within the main Sanity configuration. It utilizes the sanity/presentation package to define document-to-route mappings and location-based metadata.

Plugin Registration

The Presentation tool is registered in the plugins array of the Sanity configuration. It consumes the resolve object, which contains the logic for finding documents and their locations.

Key Components

Component	Description
mainDocuments	Defines the relationship between URL patterns and GROQ filters to identify primary documents for a route.
locations	Maps specific document types to one or more frontend URLs where they are rendered.
resolveHref	A utility function used within resolvers to generate valid frontend paths based on document slugs.
VisualEditing	A Next.js component that enables the interactive overlay in the preview.

Sources: sanity/plugins/resolve.ts:10-23, app/(personal)/layout.tsx:81, sanity/plugins/resolve.ts:8

Document Mapping and Route Resolution

The resolver logic is split into two primary structures: mainDocuments and locations. These work together to ensure that the Studio knows exactly which document is being viewed in the preview frame.

Main Documents Configuration

The mainDocuments array tells the Presentation tool which document is the "owner" of a specific URL. It uses route patterns and GROQ filters to match the $slug parameter from the URL to a document in the Content Lake.

export const mainDocuments = defineDocuments([
  {
    route: '/projects/:slug',
    filter: `_type == "project" && slug.current == $slug`,
  },
  {
    route: '/:slug',
    filter: `_type == "page" && slug.current == $slug`,
  },
])

Sources: sanity/plugins/resolve.ts:10-20

Locations Resolver

The locations object provides metadata about where a document is used. This allows the Studio to show a list of "Locations" for a document, helping editors understand the impact of their changes.

• Singletons: Documents like settings or home are mapped to fixed messages or the root path.
• Dynamic Documents: Documents like project and page use a resolve function to dynamically generate their titles and URLs using the resolveHref utility.

Sources: sanity/plugins/resolve.ts:22-54

Data Flow for Visual Editing

The Presentation Tool Resolver enables a bi-directional flow between the Studio and the Frontend. This is supported by Content Source Maps (Stega) which embed metadata into the JSON responses.

Implementation Details

Configuration in sanity.config.ts

The resolver is integrated by importing the entire module from resolve.ts and passing it to the plugin:

presentationTool({
  resolve,
  previewUrl: {
    previewMode: { enable: '/api/draft-mode/enable' }
  },
})

Sources: sanity.config.ts:54-57

Stega and Source Maps

For the resolver to allow "click-to-edit" functionality, the Sanity client must be configured with stega. The client in this project filters stega encoding to specifically target the title field while using default filters for other properties.

Sources: sanity/lib/client.ts:8-18

Conclusion

The Presentation Tool Resolver is the central logic hub for visual authoring. By defining mainDocuments for route-to-document matching and locations for document-to-URL discovery, it provides a seamless editing experience where content and its visual representation are tightly coupled.

Sources: sanity/plugins/resolve.ts:1-5, sanity.config.ts:54-57