Back

gt-sanity@4.0.0

Fernando Aviles avatarFernando Aviles
gt-sanityv4.0.0sanitycmstranslationmajor

Overview

gt-sanity v4 targets the Sanity 6 Studio. Sanity moved from @sanity/ui 3 to @sanity/ui 4 in 6.9.2, and the Studio packages that carry that change are runtime singletons, so the plugin now resolves them from your Studio instead of bundling its own copies.

Studios on Sanity 6.0 through 6.8 are still on the @sanity/ui 3 generation and should stay on gt-sanity 3.1.x. Upgrade Sanity to 6.9.2 or later first, then move to v4.

Nothing about the plugin's API or your stored content changes in v4. If your Studio is on Sanity 6.9.2 or later, upgrading is an install.

Breaking changes

Sanity 6.9.2 and @sanity/ui 4 required

The sanity peer range is now ^6.9.2. It was previously >=5.0.0, which admitted Sanity 6 even though the plugin's dependencies pinned the Sanity 5 generation. Installs resolved cleanly instead of warning, so a duplicated Studio runtime could appear with no visible signal.

Note that this is Sanity 6.9.2, not any Sanity 6. @sanity/ui 4 landed in 6.9.2, so Studios on 6.0 through 6.8 are still on the @sanity/ui 3 generation. Upgrade Sanity first, then move to gt-sanity 4.

Studio packages are now peer dependencies

@sanity/ui, @sanity/icons, @sanity/schema, and @sanity/mutator were regular dependencies and are now peer dependencies resolved from the host Studio. Installing them alongside a different Sanity generation nested a second copy, which produced duplicate schema registries and duplicate styled-components theme contexts. A Sanity 6.9.2+ Studio already provides all four, so no new install step is needed.

The floors for @sanity/document-internationalization and sanity-plugin-internationalized-array rose to ^6.2.30 and ^5.1.27. The previous floors could resolve to releases that only support Sanity 5, a second path to a duplicated runtime. The unused @sanity/util dependency was removed.

ESM-only

The CommonJS build and the require export condition are removed, following @sanity/ui 4. Import the plugin with ESM import syntax.

Node.js 22.12 or later

Up from 18, matching sanity and @sanity/ui 4.

Staying on Sanity 5

gt-sanity 3.1.x remains the supported line for Sanity 5 Studios, and for Sanity 6.0 through 6.8. It is not deprecated, and pinning to it is a valid choice if you are not ready to move your Studio.

npm install gt-sanity@^3.1

The v3 feature set is unchanged. When you do upgrade Sanity to 6.9.2 or later, moving to v4 needs no code or content changes.

Fixes

A few bugs were fixed alongside the upgrade:

  • Publish Translations dropped whole translation groups when a source locale had been relabelled (en to en-US, for example). Publishing identified the source entry in translation.metadata by its language label, so a metadata document written before the change matched nothing and the group was skipped with no error. Source and translation entries are now told apart by which document they reference.
  • Translate All and Import All now report progress. Both previously looked idle while a run was still in flight, since each only tracked its own request rather than the enqueued work.
  • gtStructureItems pins a Sanity API version, clearing a deprecation warning Sanity has said will become an error.