Back

gt-sanity@4.0.0

Fernando Aviles avatarFernando Aviles
gt-sanityv4.0.0sanitycmstranslationmajor

Overview

gt-sanity v4 targets 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 remain 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 only requires installation.

Breaking changes

Sanity 6.9.2 and @sanity/ui 4 required

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

Note that this is Sanity 6.9.2, not any Sanity 6 version. @sanity/ui 4 was introduced in 6.9.2, so Studios on versions 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, resulting in duplicate schema registries and styled-components theme contexts. A Sanity 6.9.2+ Studio already provides all four, so no new installation step is required.

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

ESM-only

The CommonJS build and the require export condition have been removed, in line with @sanity/ui 4. Import the plugin using ESM import syntax.

Node.js 22.12 or later

Raised from 18, in line with sanity and @sanity/ui 4.

Staying on Sanity 5

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

npm install gt-sanity@^3.1

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

Fixes

A few bugs were fixed alongside the upgrade:

  • Publish Translations dropped entire 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 without an error. Source and translation entries are now distinguished by the document they reference.
  • Translate All and Import All now report progress. Both previously appeared idle while a run was still in progress, as each tracked only its own request rather than the queued work.
  • gtStructureItems pins a Sanity API version, clearing a deprecation warning that Sanity has said will become an error.