What to Watch Out for When Improving an Existing Sanity Instance

At Nearform, we understand that software development does not end at the initial launch. Requirements change and the team’s initial assumptions are tested. Enhancing a system in production demands a nuanced approach to implementation that is distinct from an initial build. Our extensive experience with Sanity CMS has provided us with valuable insights in resolving these scenarios. Read on to learn about some of our strategies to refine an existing Sanity instance so that it continues to evolve with your business needs.

Assessing Your Content Strategy

As a content management system, the most significant changes to an existing Sanity instance will usually deal with how data is organized on the site or changes to the workflow 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 determined that changing an established 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.

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 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!