What to Watch Out for When Improving an Existing Sanity Instance

At Nearform, we understand that software development does not end on launch day. Requirements change and the team’s initial assumptions will be tested. Enhancing a system in production demands a new approach to implementation, distinct from an initial build. Read on to uncover some of our strategies, learned through deep experience with Sanity CMS, to refine an existing Sanity instance so that it evolves with your business needs.

Assessing Your Content Strategy

As a content management system, the most significant changes to an existing Sanity instance usually deal with either how data is organized on the site or changes to the workflows that content admins use to update the site.

Some of the common kinds of changes we’re referring to are:

• Restructuring a data type to reflect business needs
• Assisting content admins by renaming or reordering fields
• Updating field validation within Sanity Studio to reduce errors in content entry

In Sanity Studio, the form fields that content admins fill out are directly linked to the underlying content schema. Resolving pain points with those form fields often requires updating the schema.

It should be noted that schema changes are typically breaking changes, and caution should be taken when changing properties on schema types. The schema configuration for a content type is your API contract. This means that changes to a schema can have cascading effects throughout your application. These changes can lead to broken content from the Content Lake. Without proper tests or type safety in place, that broken content will also break components in your frontend.

For these reasons, it’s worth considering whether directly changing the existing schema is really the best way forward. Are there other ways to accomplish what’s being asked? Maybe stakeholders have asked for a brand new data type, but the need could be met with a single field added to an existing data type. Conversely, maybe you’re in a situation where the chain of dependencies is less complex if you set up a new data type that gets handled separately on the frontend. Maybe your approach doesn’t get you all the way there, but it might be the first step in moving incrementally to an ideal state.

Making Seamless Updates

If you’ve decided that changing an existing schema is the best way to solve a problem you’re facing, there are ways to make the update as seamless as possible and avoid breaking changes.

First, if there is a need to update a form field, you can update the title of a field type with no consequences. (This is the label that’s shown in the Studio UI.) However, changing the name of a field will require downstream changes to the query and frontend components. If the naming of fields in the Studio is causing confusion for your content editors, we suggest editing the title for the various fields and leaving the name as is.

Sometimes a site’s content strategy will shift in a way that requires replacing or completely overhauling a form field. As of version 3.26.0, Sanity Studio supports deprecating document fields with the deprecated property. You can set a deprecation reason that is displayed to the user in the Studio and guide the user towards the updated or new schema. By deprecating fields, you can phase out legacy fields over a period of time. Content admins will be able to start slowly using the new fields, which will allow you to come back and remove the deprecated field later.

Don't forget that renaming a field, adding new validation conditions, or moving existing fields into an array or object type will require migrating your established content to the new data structure. Sanity has well-documented guides on how to do this and has made the process rather painless.

Your Partner in Content Strategy

Our team of experts are well versed in schema change management. If your site needs significant updates, or you are about to set out on a migration to Sanity and want to make sure your content strategy is robust from the start, email our team - we’d love to help!