@sanity/client

[![gzip size][gzip-badge]][bundlephobia] [![size][size-badge]][bundlephobia]

JavaScript client for Sanity. Works in modern browsers, as well as runtimes like [Node.js], [Bun], [Deno], and [Edge Runtime]

QuickStart

Install the client with a package manager:

npm install @sanity/client

Import and create a new client instance, and use its methods to interact with your project's [Content Lake]. Below are some simple examples in plain JavaScript. Read further for more comprehensive documentation.

// sanity.js
import {createClient} from '@sanity/client'
// Import using ESM URL imports in environments that supports it:
// import {createClient} from 'https://esm.sh/@sanity/client'

export const client = createClient({
  projectId: 'your-project-id',
  dataset: 'your-dataset-name',
  useCdn: true, // set to `false` to bypass the edge cache
  // Set default headers to be included with all requests
  headers: {
    'X-Custom-Header': 'custom-value'
  },
  apiVersion: '2025-02-06', // use current date (YYYY-MM-DD) to target the latest API version. Note: this should always be hard coded. Setting API version based on a dynamic value (e.g. new Date()) may break your application at a random point in the future.
  // token: process.env.SANITY_SECRET_TOKEN // Needed for certain operations like updating content, accessing drafts or using draft perspectives
})

// uses GROQ to query content: https://www.sanity.io/docs/groq
export async function getPosts() {
  const posts = await client.fetch('*[_type == "post"]')
  return posts
}

export async function createPost(post: Post) {
  const result = client.create(post)
  return result
}

export async function updateDocumentTitle(_id, title) {
  const result = client.patch(_id).set({title})
  return result
}

Table of contents

• QuickStart
• Requirements
• Installation
• API
  • Creating a client instance
    • ESM
    • CommonJS
    • TypeScript
    • Next.js App Router
    • Bun
    • Deno
    • Edge Runtime
    • Browser ESM CDN
    • UMD
  • Specifying API version
  • Request tags
  • Performing queries
  • Using perspectives
    • published
    • drafts
    • raw
  • Fetching Content Source Maps
    • Using Visual editing with steganography
    • Creating Studio edit intent links
  • Listening to queries
  • Fetch a single document
  • Fetch multiple documents in one go
  • Creating documents
  • Creating/replacing documents
  • Creating if not already present
  • Patch/update a document
  • Setting a field only if not already present
  • Removing/unsetting fields
  • Incrementing/decrementing numbers
  • Patch a document only if revision matches
  • Adding elements to an array
  • Appending/prepending elements to an array
  • Deleting an element from an array
  • Delete documents
  • Multiple mutations in a transaction
  • Clientless patches & transactions
  • Release and version operations
  • Uploading assets
    • Examples: Uploading assets from Node.js
    • Examples: Uploading assets from the Browser
    • Examples: Specify image metadata to extract
  • Deleting an asset
  • Mutation options
  • Aborting a request
    • 1. Abort a request by passing an AbortSignal with the request options
    • 2. Cancel a request by unsubscribing from the Observable
  • Get client configuration
  • Set client configuration
  • Actions
    • Action options
    • Create Action
    • Delete Action
    • Edit Action
    • Publish Action
    • Unpublish Action
    • Version actions
      • Create Version Action
      • Discard Version Action
      • Replace Version Action
      • Unpublish Version Action
    • Release Actions
      • Create Release Action
      • Edit Release Action
      • Published Release Action
      • Schedule Release Action
      • Unschedule Release Action
      • Archive Release Action
      • Unarchive Release Action
      • Delete Release Action
  • Agent Actions
    • Overview
    • Generating Content
      • Generating images
      • Example: Using GROQ in instructionParams
      • Example: Using the async flag
    • Transforming Documents
      • Transforming images
      • Image descriptions
      • Example: Field-based transformation
    • Translating Documents
      • Example: Storing language in a field
    • Prompt the LLM
    • Patch with a schema-aware API
  • Media Library API
    • Getting video playback information
    • Working with signed playback information
    • Downloading MP4 renditions
• License
• From v5
  • The default useCdn is changed to true
• From v4
  • No longer shipping ES5
  • Node.js v12 no longer supported
  • The default export is replaced with the named export createClient
  • client.assets.delete is removed
  • client.assets.getImageUrl is removed, replace with @sanity/image-url
  • SanityClient static properties moved to named exports
  • client.clientConfig is removed, replace with client.config()
  • client.isPromiseAPI() is removed, replace with an instanceof check
  • client.observable.isObservableAPI() is removed, replace with an instanceof check
  • client._requestObservable is removed, replace with client.observable.request
  • client._dataRequest is removed, replace with client.dataRequest
  • client._create_ is removed, replace with one of client.create, client.createIfNotExists or client.createOrReplace
  • client.patch.replace is removed, replace with client.createOrReplace
  • client.auth is removed, replace with client.request

Requirements

Sanity Client transpiles syntax for [modern browsers]. The JavaScript runtime must support ES6 features such as class, rest parameters, spread syntax and more. Most modern web frameworks, [browsers][modern browsers], and developer tooling supports ES6 today.

For legacy ES5 environments we recommend v4.

Installation

The client can be installed from [npm]:

npm install @sanity/client

# Alternative package managers
yarn add @sanity/client
pnpm install @sanity/client

A