@sanity/sdk-react 2.5.0 → 2.7.0

package/README.md

@@ -322,6 +322,29 @@ The SDK handles updating the document state automatically:
 - `publishDocument()` copies draft → published, deletes draft
 - `discardDraft()` deletes draft, reverts to published
 
+#### LiveEdit Documents
+
+For documents that don't need the draft/published workflow (such as settings, configuration, or real-time collaborative documents), you can use **liveEdit mode** by setting `liveEdit: true` in the document handle:
+
+```tsx
+const settingsHandle: DocumentHandle = {
+  documentId: 'site-settings',
+  documentType: 'settings',
+  liveEdit: true, // Edits apply directly without creating a draft
+}
+
+// Edits are applied immediately to the published document
+const editSettings = useEditDocument(settingsHandle)
+```
+
+**When using liveEdit documents:**
+
+- Drafts will not be created when the document is edited
+- Edits will be applied directly to the published document
+- `publishDocument()`, `unpublishDocument()`, and `discardDraft()` actions cannot be used (since liveEdit documents are always published and do not have drafts)
+
+For more details, see the [Sanity documentation on liveEdit documents](https://www.sanity.io/docs/content-lake/drafts).
+
 ---
 
 ### Real-Time Behavior
@@ -340,43 +363,165 @@ Any mutation to a subscribed document (even fields you don't display) will trigg
 
 ### Multi-Project Access
 
-#### Specify Source in Handle
+The SDK supports accessing documents from multiple projects and datasets simultaneously. There are two main approaches:
+
+#### Approach 1: Specify Project/Dataset Directly in the Handle
+
+Pass `projectId` and `dataset` directly in document handles to fetch data from specific projects (note that any `projectId` and `dataset` pair you pass must be defined in your application’s array of [SanityConfig objects](https://www.sanity.io/docs/app-sdk/sdk-configuration#d95b8773097c)):
 
 ```tsx
-const handle: DocumentHandle = {
-  documentId: 'xyz',
-  documentType: 'product',
-  projectId: 'project-a',
-  dataset: 'production',
+import {useDocument} from '@sanity/sdk-react'
+
+function MultiProjectComponent() {
+  // Fetch from Project A
+  const {data: productA} = useDocument({
+    documentId: 'product-123',
+    documentType: 'product',
+    projectId: 'project-a',
+    dataset: 'production',
+  })
+
+  // Fetch from Project B
+  const {data: productB} = useDocument({
+    documentId: 'product-456',
+    documentType: 'product',
+    projectId: 'project-b',
+    dataset: 'staging',
+  })
+
+  return (
+    <div>
+      <h2>{productA?.title} (Project A)</h2>
+      <h2>{productB?.title} (Project B)</h2>
+    </div>
+  )
 }
 ```
 
-#### Use Resource Provider Context
+#### Approach 2: Use ResourceProvider to Set Context
+
+Wrap components in `ResourceProvider` to set default project/dataset values for all child components:
 
 ```tsx
 // App.tsx
-import {ResourceProvider} from '@sanity/sdk-react'
+import {ResourceProvider, useDocument, useSanityInstance} from '@sanity/sdk-react'
 
-import {ProductCard} from './ProductCard'
+function ProductCard({productId}: {productId: string}) {
+  // Get the current project/dataset from context
+  const {config} = useSanityInstance()
+
+  // No need to specify projectId/dataset - inherited from ResourceProvider
+  const {data: product} = useDocument({
+    documentId: productId,
+    documentType: 'product',
+  })
 
-export function WrappedProductCard() {
   return (
-    <ResourceProvider projectId="project-a" dataset="production">
-      <ProductCard productId="xyz" />
-    </ResourceProvider>
+    <div>
+      <h3>{product?.title}</h3>
+      <p>
+        From: {config.projectId}.{config.dataset}
+      </p>
+    </div>
   )
 }
 
-// ProductCard.tsx
-import {useProjectId, useDataset} from '@sanity/sdk-react'
+export function MultiProjectApp() {
+  return (
+    <div>
+      {/* Products from Project A */}
+      <ResourceProvider projectId="project-a" dataset="production" fallback={<div>Loading...</div>}>
+        <h2>Project A Products</h2>
+        <ProductCard productId="product-123" />
+        <ProductCard productId="product-456" />
+      </ResourceProvider>
+
+      {/* Products from Project B */}
+      <ResourceProvider projectId="project-b" dataset="staging" fallback={<div>Loading...</div>}>
+        <h2>Project B Products</h2>
+        <ProductCard productId="product-789" />
+      </ResourceProvider>
+    </div>
+  )
+}
+```
 
-function ProductCard({productId}: {productId: string}) {
-  const projectId = useProjectId() // "project-a" from nearest configured ResourceProvider
-  const dataset = useDataset() // "production" from nearest configured ResourceProvider
-  // ...
+**Key Points:**
+
+- When using hooks that take document handles as arguments (such useDocument, useEditDocument, useQuery, etc.), the document handles’ `projectId` and `dataset` values can be explicitly set to fetch documents from arbitrary projects and datasets
+- The ResourceProvider component is used to create a project ID and dataset context that child components will inherit from; this can negate the need to specify the project ID and dataset values for document handles in hooks called by child components
+- Use `useSanityInstance()` to access the context configuration for the current component: `const {config} = useSanityInstance()`
+- You can nest ResourceProvider components to create component trees with different project/dataset configurations — but be aware that, when the project ID and dataset values for document handles are _not_ specified, the project ID and dataset from the closest ResourceProvider context will be used
+- Regardless of the approach you use, the project IDs and dataset names you reference (whether in document handles or ResourceProviders) must be enumerated in your application’s [SanityConfig objects](https://www.sanity.io/docs/app-sdk/sdk-configuration#d95b8773097c)
+
+---
+
+### Using the SDK inside Sanity Studio
+
+The SDK can be embedded directly inside a Sanity Studio with zero manual configuration. Sanity Studio provides `SDKStudioContext` automatically, so `SanityApp` derives `projectId`, `dataset`, and auth from the Studio's workspace without any setup.
+
+#### Zero-config setup (recommended)
+
+Sanity Studio automatically provides `SDKStudioContext` to SDK components, so your SDK component needs no `config` prop at all:
+
+```tsx
+import {SanityApp} from '@sanity/sdk-react'
+
+// Inside a Sanity Studio — no config needed:
+function MyStudioTool() {
+  return (
+    <SanityApp fallback={<div>Loading...</div>}>
+      <MyComponent />
+    </SanityApp>
+  )
 }
 ```
 
+Under the hood, the Studio wraps its component tree with `SDKStudioContext.Provider`, passing its workspace to the SDK:
+
+```tsx
+import {SDKStudioContext} from '@sanity/sdk-react'
+import {useWorkspace} from 'sanity'
+
+// This is done automatically by Sanity Studio — shown here for reference only
+function StudioSDKWrapper({children}) {
+  const workspace = useWorkspace()
+  return <SDKStudioContext.Provider value={workspace}>{children}</SDKStudioContext.Provider>
+}
+```
+
+#### Explicit config takes precedence
+
+If you pass a `config` prop to `SanityApp`, this config will take precedence over any workspace config picked up by `SDKStudioContext`:
+
+```tsx
+// This uses the explicit config, not the Studio workspace
+<SanityApp config={{projectId: 'other-project', dataset: 'staging'}} fallback={<Loading />}>
+  <MyComponent />
+</SanityApp>
+```
+
+#### Reactive auth token sync
+
+If the Studio provides a reactive token source via `workspace.auth.token`, the SDK subscribes to it and stays in sync automatically. The Studio remains the single authority for auth — the SDK does not perform its own token refresh.
+
+For older Studios that don't expose a token source, the SDK falls back to discovering the auth token from `localStorage` or cookie auth.
+
+#### Migrating from `studioMode`
+
+The `studioMode` config field is deprecated. If you are currently using it, the recommended replacement is to use the zero-config `SDKStudioContext` approach described above — which requires no `config` prop at all.
+
+If you need to pass an explicit config, replace `studioMode` with `studio`:
+
+```diff
+ const config: SanityConfig = {
+   projectId: 'my-project',
+   dataset: 'production',
+-  studioMode: { enabled: true },
++  studio: {},
+ }
+```
+
 ---
 
 ### TypeScript & TypeGen