Sanity

Sanity Connector Guide

This guide covers how to connect Whalesync to a Sanity project, what you need to do in Sanity first, and which fields sync.

In Whalesync terms, a Sanity dataset is the base you pick, each document type in your Studio schema is a table, and each document is a record.

Before you connect: deploy your Studio schema

Caution

Whalesync reads your document types and fields from the Studio schema that is deployed to your dataset. Sanity's Content Lake has no built-in schema, so until you deploy one Whalesync cannot list any tables. A dataset without a deployed schema shows as No schema deployed in the dataset picker.

Deploying takes one command in your Sanity Studio project (Studio 3.88 or newer):

npx sanity schema deploy

Run it as a logged-in Studio developer, or with an Editor-role token in SANITY_AUTH_TOKEN. See Sanity's guide: Schema deployment.

Whenever you change your Studio schema, deploy it again and then refresh the schema in Whalesync so the new fields appear.

Connecting to Sanity

Whalesync connects with a Sanity API token. See Authorize Sanity for the steps to create one.

1. In Whalesync, choose Sanity and paste the token.
2. If the token can access more than one project, enter the Project ID as well. Robot tokens are usually scoped to one project, so most people can leave it blank.
3. Pick the dataset to sync. Datasets without a deployed schema are listed but cannot be selected until you deploy one.

Syncing Data

Every document type in the deployed schema is available as a table, including types that have no documents yet. Nested objects (for example an seo object with metaTitle and metaDescription) appear as separate fields named seo / Meta title, so each part can be mapped on its own.

Supported Fields

Whalesync does not support every Sanity field type yet. If you need one that is missing, reach out and let us know.

Sanity type	Status	Notes
String	✅ Supported	A string with an options.list is offered as a select, but Whalesync does not enforce the list.
Text	✅ Supported
Number	✅ Supported
Boolean	✅ Supported
Date	✅ Supported	Date only, no time.
Datetime	✅ Supported
URL	✅ Supported
Email	✅ Supported
Slug	✅ Supported	Synced as the slug text.
Reference (one target type)	✅ Supported	Synced as a link to the target document type. Weak references stay weak.
Array of references	✅ Supported	Synced as a multi-link field.
Array of strings	✅ Supported
Object	✅ Supported	Flattened into one field per sub-field, up to three levels deep. Deeper objects are synced as JSON, read only.
Reference (several target types)	➡️ Supported (1-Way)	Read only. Whalesync links point at one table, so the target document id is synced as text.
Portable Text (block content)	➡️ Supported (1-Way)	Read only, converted to HTML. Custom blocks inside the text, such as images and code, are left out.
Image	➡️ Supported (1-Way)	Read only, synced as the image's CDN URL.
File	➡️ Supported (1-Way)	Read only, synced as the file's CDN URL.
Geopoint	✅ Supported (as JSON)	Read only.
Array of objects or images	✅ Supported (as JSON)	Read only.
Fields marked readOnly in the Studio	➡️ Supported (1-Way)	Read only in Whalesync too.
Cross-dataset and global references	✅ Supported (as JSON)	Read only.

Additional Fields

Whalesync adds fields that are not part of your Studio schema.

Field	Explanation	Writable
Record ID	The document's _id. When creating a document from another app, map this field to choose the id; it cannot be changed afterwards.	Once, on create
Draft	True when the document has an unpublished draft (or is only a draft). See Drafts and publishing.	Yes
Published	True when a published version of the document exists.	No
Created at	The document's _createdAt.	No
Updated at	The document's _updatedAt. When a draft exists, this is the draft's timestamp.	No

Drafts and publishing

In Sanity, a document with unpublished edits exists twice: the published version and a draft. Whalesync treats the pair as one record.

• Reading: Whalesync syncs the latest content. If a draft exists, you see the draft's values, and the Draft field is true.
• Writing: by default, a change Whalesync makes is applied to the published document and to the draft if there is one, so it goes live right away and is not undone the next time someone clicks Publish in the Studio.
• Keeping a change unpublished: map the Draft field and set it to true. Whalesync then writes only to the draft, creating one from the published document if needed. Nothing goes live until you publish.
• Publishing from Whalesync: set Draft to false on a record that has a draft. Whalesync publishes the draft (with your changes) and removes it, just like Publish in the Studio.
• New records are created as published documents, or as drafts when Draft is set to true.
• Deleting a record removes both the published document and its draft.

Things to Keep in Mind

• The deployed schema is the schema. A field you add in Studio code does not exist for Whalesync until you run npx sanity schema deploy again and refresh the schema in Whalesync.
• The token needs the Editor role. A Viewer token can read your dataset but every create, update, and delete fails with a permissions error.
• Sanity refuses to delete a referenced document. If another document holds a strong reference to it, Sanity blocks the delete until the reference is removed or made weak.
• Content Releases are not synced. Documents that only exist inside a release are ignored.
• Studio autosaves as you type, so a document you are editing in the Studio updates its draft many times. Whalesync syncs the latest state.
• Images and files can be read but not written yet. Uploading assets from another app into Sanity is not supported in this version.