@sanity/sdk-react 2.7.0 → 3.0.0-rc.0

package/src/components/SanityApp.tsx

@@ -1,4 +1,9 @@
-import {type DocumentSource, isStudioConfig, type SanityConfig} from '@sanity/sdk'
+import {
+  DEFAULT_RESOURCE_NAME,
+  type DocumentResource,
+  isStudioConfig,
+  type SanityConfig,
+} from '@sanity/sdk'
 import {type ReactElement, useContext, useEffect, useMemo} from 'react'
 
 import {SDKStudioContext, type StudioWorkspaceHandle} from '../context/SDKStudioContext'
@@ -11,15 +16,17 @@ import {isInIframe, isLocalUrl} from './utils'
  */
 export interface SanityAppProps {
   /**
-   * One or more SanityConfig objects providing a project ID and dataset name.
-   * Optional when `SanityApp` is rendered inside an `SDKStudioContext` provider
-   * (e.g. inside Sanity Studio) — the config is derived from the workspace
-   * automatically.
+   * Core configuration for the SDK instance (auth, studio, perspective).
+   * Optional when `SanityApp` is rendered inside an `SDKStudioContext`
+   * provider (e.g. inside Sanity Studio) — the config is derived from
+   * the workspace automatically.
    */
-  config?: SanityConfig | SanityConfig[]
-  /** @deprecated use the `config` prop instead. */
-  sanityConfigs?: SanityConfig[]
-  sources?: Record<string, DocumentSource>
+  config?: SanityConfig
+  /**
+   * Named document resources for the application. The resource keyed `"default"`
+   * is used automatically when no explicit resource is specified in hooks.
+   */
+  resources?: Record<string, DocumentResource>
   children: React.ReactNode
   /* Fallback content to show when child components are suspending. Same as the `fallback` prop for React Suspense. */
   fallback: React.ReactNode
@@ -28,16 +35,22 @@ export interface SanityAppProps {
 const REDIRECT_URL = 'https://sanity.io/welcome'
 
 /**
- * Derive a SanityConfig from a Studio workspace handle.
- * Maps the workspace's projectId, dataset, and reactive auth token into
- * the SDK's config shape.
+ * Derive a SanityConfig and resources map from a Studio workspace handle.
  */
-function deriveConfigFromWorkspace(workspace: StudioWorkspaceHandle): SanityConfig {
+function deriveFromWorkspace(workspace: StudioWorkspaceHandle): {
+  config: SanityConfig
+  resources: Record<string, DocumentResource>
+} {
   return {
-    projectId: workspace.projectId,
-    dataset: workspace.dataset,
-    studio: {
-      auth: workspace.auth.token ? {token: workspace.auth.token} : undefined,
+    config: {
+      studio: {
+        authenticated: workspace.authenticated,
+        auth: workspace.auth.token ? {token: workspace.auth.token} : undefined,
+        projectId: workspace.projectId,
+      },
+    },
+    resources: {
+      [DEFAULT_RESOURCE_NAME]: {projectId: workspace.projectId, dataset: workspace.dataset},
     },
   }
 }
@@ -49,57 +62,49 @@ function deriveConfigFromWorkspace(workspace: StudioWorkspaceHandle): SanityConf
  * as well as application context and state which is used by the Sanity React hooks. Your application
  * must be wrapped with the SanityApp component to function properly.
  *
- * The `config` prop on the SanityApp component accepts either a single {@link SanityConfig} object, or an array of them.
- * This allows your app to work with one or more of your organization's datasets.
- *
- * When rendered inside a Sanity Studio that provides `SDKStudioContext`, the `config` prop is
- * optional — `SanityApp` will automatically derive `projectId`, `dataset`, and auth from the
- * Studio workspace.
+ * The `config` prop accepts a {@link SanityConfig} object. Use the `resources` prop to declare
+ * one or more named data resources for your app.
  *
- * @remarks
- * When passing multiple SanityConfig objects to the `config` prop, the first configuration in the array becomes the default
- * configuration used by the App SDK Hooks.
+ * When rendered inside a Sanity Studio that provides `SDKStudioContext`, the `config` and `resources`
+ * props are optional — `SanityApp` will automatically derive them from the Studio workspace.
  *
- * When both `config` and `SDKStudioContext` are available, the explicit `config` takes precedence.
+ * When both `config` and `SDKStudioContext` are available, the explicit props take precedence.
  *
  * @category Components
  * @param props - Your Sanity configuration and the React children to render
  * @returns Your Sanity application, integrated with your Sanity configuration and application context
  *
- * @example
+ * @example Single project
  * ```tsx
- * import { SanityApp, type SanityConfig } from '@sanity/sdk-react'
+ * import { SanityApp } from '@sanity/sdk-react'
  *
- * import MyAppRoot from './Root'
- *
- * // Single project configuration
- * const mySanityConfig: SanityConfig = {
- *   projectId: 'my-project-id',
- *   dataset: 'production',
+ * export default function MyApp() {
+ *   return (
+ *     <SanityApp
+ *       resources={{
+ *         default: { projectId: 'my-project-id', dataset: 'production' },
+ *       }}
+ *       fallback={<div>Loading…</div>}
+ *     >
+ *       <MyAppRoot />
+ *     </SanityApp>
+ *   )
  * }
+ * ```
  *
- * // Or multiple project configurations
- * const multipleConfigs: SanityConfig[] = [
- *   // Configuration for your main project. This will be used as the default project for hooks.
- *   {
- *     projectId: 'marketing-website-project',
- *     dataset: 'production',
- *   },
- *   // Configuration for a separate blog project
- *   {
- *     projectId: 'blog-project',
- *     dataset: 'production',
- *   },
- *   // Configuration for a separate ecommerce project
- *   {
- *     projectId: 'ecommerce-project',
- *     dataset: 'production',
- *   }
- * ]
+ * @example Multiple resources
+ * ```tsx
+ * import { SanityApp } from '@sanity/sdk-react'
  *
  * export default function MyApp() {
  *   return (
- *     <SanityApp config={mySanityConfig} fallback={<div>Loading…</div>}>
+ *     <SanityApp
+ *       resources={{
+ *         default: { projectId: 'abc123', dataset: 'production' },
+ *         'blog-project': { projectId: 'def456', dataset: 'production' },
+ *       }}
+ *       fallback={<div>Loading…</div>}
+ *     >
  *       <MyAppRoot />
  *     </SanityApp>
  *   )
@@ -110,29 +115,42 @@ export function SanityApp({
   children,
   fallback,
   config: configProp,
+  resources: resourcesProp,
   ...props
 }: SanityAppProps): ReactElement {
   const studioWorkspace = useContext(SDKStudioContext)
 
-  // Derive config: explicit config takes precedence, then Studio context
-  const resolvedConfig = useMemo(() => {
-    if (configProp) return configProp
-    if (studioWorkspace) return deriveConfigFromWorkspace(studioWorkspace)
-    return []
-  }, [configProp, studioWorkspace])
+  const derived = useMemo(() => {
+    if (studioWorkspace && !configProp && !resourcesProp) {
+      return deriveFromWorkspace(studioWorkspace)
+    }
+    return null
+  }, [configProp, resourcesProp, studioWorkspace])
+
+  const resolvedConfig = useMemo<SanityConfig>(() => {
+    if (configProp) {
+      return configProp
+    }
+    if (derived) return derived.config
+    return {}
+  }, [configProp, derived])
+
+  const resolvedResources = useMemo<Record<string, DocumentResource>>(() => {
+    if (resourcesProp) return resourcesProp
+    if (derived) return derived.resources
+    return {}
+  }, [resourcesProp, derived])
 
   useEffect(() => {
     let timeout: NodeJS.Timeout | undefined
-    const primaryConfig = Array.isArray(resolvedConfig) ? resolvedConfig[0] : resolvedConfig
     const shouldRedirectWithoutConfig =
-      configProp === undefined && !studioWorkspace && !primaryConfig
+      configProp === undefined && !studioWorkspace && !resolvedConfig
 
     if (
       !isInIframe() &&
       !isLocalUrl(window) &&
-      (shouldRedirectWithoutConfig || (!!primaryConfig && !isStudioConfig(primaryConfig)))
+      (shouldRedirectWithoutConfig || (!!resolvedConfig && !isStudioConfig(resolvedConfig)))
     ) {
-      // If the app is not running in an iframe and is not a local url, redirect to core.
       timeout = setTimeout(() => {
         // eslint-disable-next-line no-console
         console.warn('Redirecting to core', REDIRECT_URL)
@@ -143,7 +161,12 @@ export function SanityApp({
   }, [configProp, resolvedConfig, studioWorkspace])
 
   return (
-    <SDKProvider {...props} fallback={fallback} config={resolvedConfig}>
+    <SDKProvider
+      {...props}
+      fallback={fallback}
+      config={resolvedConfig}
+      resources={resolvedResources}
+    >
       {children}
     </SDKProvider>
   )

package/src/components/auth/AuthBoundary.test.tsx

@@ -1,4 +1,4 @@
-import {AuthStateType, type SanityConfig} from '@sanity/sdk'
+import {AuthStateType} from '@sanity/sdk'
 import {render, screen, waitFor} from '@testing-library/react'
 import React from 'react'
 import {type FallbackProps} from 'react-error-boundary'
@@ -22,6 +22,9 @@ vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
 vi.mock('../../hooks/auth/useLogOut', () => ({
   useLogOut: vi.fn(() => async () => {}),
 }))
+vi.mock('../../hooks/comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(() => ({fetch: vi.fn()})),
+}))
 
 // Mock AuthError throwing scenario
 vi.mock('./AuthError', async (importOriginal) => {
@@ -107,24 +110,6 @@ describe('AuthBoundary', () => {
   const mockUseVerifyOrgProjects = vi.mocked(useVerifyOrgProjects)
   const testProjectIds = ['proj-test'] // Example project ID for tests
 
-  // Mock Sanity instance
-  const mockSanityInstance = {
-    instanceId: 'test-instance-id',
-    config: {
-      projectId: 'test-project',
-      dataset: 'test-dataset',
-    },
-    isDisposed: () => false,
-    dispose: () => {},
-    onDispose: () => () => {},
-    getParent: () => undefined,
-    createChild: (config: SanityConfig) => ({
-      ...mockSanityInstance,
-      config: {...mockSanityInstance.config, ...config},
-    }),
-    match: () => undefined,
-  }
-
   beforeEach(() => {
     vi.clearAllMocks()
     consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
@@ -163,7 +148,7 @@ describe('AuthBoundary', () => {
       isExchangingToken: false,
     })
     const {container} = render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
       </ResourceProvider>,
     )
@@ -180,7 +165,7 @@ describe('AuthBoundary', () => {
       token: 'exampleToken',
     })
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
       </ResourceProvider>,
     )
@@ -194,7 +179,7 @@ describe('AuthBoundary', () => {
       error: new Error('test error'),
     })
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
       </ResourceProvider>,
     )
@@ -211,7 +196,7 @@ describe('AuthBoundary', () => {
 
   it('renders children when logged in and org verification passes', () => {
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary projectIds={testProjectIds}>Protected Content</AuthBoundary>
       </ResourceProvider>,
     )
@@ -233,7 +218,7 @@ describe('AuthBoundary', () => {
 
     // Need to catch the error thrown during render. ErrorBoundary mock handles this.
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary verifyOrganization={true} projectIds={testProjectIds}>
           <div>Protected Content</div>
         </AuthBoundary>
@@ -265,7 +250,7 @@ describe('AuthBoundary', () => {
     })
 
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary verifyOrganization={false} projectIds={testProjectIds}>
           <div>Protected Content</div>
         </AuthBoundary>
@@ -290,7 +275,7 @@ describe('AuthBoundary', () => {
     mockUseVerifyOrgProjects.mockImplementation(() => null)
 
     render(
-      <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourceProvider resource={{projectId: 'p', dataset: 'd'}} fallback={null}>
         <AuthBoundary projectIds={testProjectIds}>
           <div>Protected Content</div>
         </AuthBoundary>

package/src/components/auth/LoginError.test.tsx

@@ -9,6 +9,10 @@ vi.mock('../../hooks/auth/useLogOut', () => ({
   useLogOut: vi.fn(() => async () => {}),
 }))
 
+vi.mock('../../hooks/comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(() => ({fetch: vi.fn()})),
+}))
+
 describe('LoginError', () => {
   it('shows authentication error and retry button', async () => {
     const mockReset = vi.fn()
@@ -21,6 +25,7 @@ describe('LoginError', () => {
     )
 
     expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+
     const retryButton = screen.getByRole('button', {name: 'Retry'})
     fireEvent.click(retryButton)
 

package/src/components/auth/LoginError.tsx

@@ -1,15 +1,19 @@
 import {ClientError} from '@sanity/client'
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
 import {
   AuthStateType,
   getClientErrorApiBody,
   getClientErrorApiDescription,
+  isDatasetResource,
   isProjectUserNotFoundClientError,
 } from '@sanity/sdk'
-import {useCallback, useEffect, useState} from 'react'
+import {useCallback, useContext, useEffect, useState} from 'react'
 import {type FallbackProps} from 'react-error-boundary'
 
+import {ResourceContext} from '../../context/DefaultResourceContext'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLogOut} from '../../hooks/auth/useLogOut'
+import {useWindowConnection} from '../../hooks/comlink/useWindowConnection'
 import {Error} from '../errors/Error'
 import {AuthError} from './AuthError'
 import {ConfigurationError} from './ConfigurationError'
@@ -36,12 +40,22 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
 
   const logout = useLogOut()
   const authState = useAuthState()
+  const resource = useContext(ResourceContext)
+  const projectId = resource && isDatasetResource(resource) ? resource.projectId : undefined
 
   const [authErrorMessage, setAuthErrorMessage] = useState(
     'Please try again or contact support if the problem persists.',
   )
   const [showRetryCta, setShowRetryCta] = useState(true)
 
+  /**
+   * TODO: before merge update message-protocol package to include the new message type
+   */
+  const {fetch} = useWindowConnection({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
   const handleRetry = useCallback(async () => {
     await logout()
     resetErrorBoundary()
@@ -55,6 +69,13 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
           const description = getClientErrorApiDescription(error)
           if (description) setAuthErrorMessage(description)
           setShowRetryCta(false)
+          /**
+           * Handoff to dashboard to enable the request access flow for the project.
+           */
+          fetch('dashboard/v1/auth/access/request', {
+            resourceType: 'project',
+            resourceId: projectId,
+          })
         } else {
           setShowRetryCta(true)
           handleRetry()
@@ -73,7 +94,7 @@ export function LoginError({error, resetErrorBoundary}: LoginErrorProps): React.
       setAuthErrorMessage(error.message)
       setShowRetryCta(true)
     }
-  }, [authState, handleRetry, error])
+  }, [authState, handleRetry, error, fetch, projectId])
 
   return (
     <Error

package/src/config/handles.ts

@@ -0,0 +1,53 @@
+import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
+
+// React-layer types — shadow core equivalents when imported from @sanity/sdk-react.
+// resource is optional here and resolved from context by normalization,
+// whereas core's DocumentHandle/ResourceHandle require resource explicitly.
+
+/**
+ * SDK React ResourceHandle with optional explicit resource field.
+ * Resource is resolved from context when not provided.
+ * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
+ * if there is a matching resource by that name.
+ * @public
+ */
+export interface ResourceHandle<
+  TProjectId extends string = string,
+  TDataset extends string = string,
+> {
+  resource?: DocumentResource<TProjectId, TDataset>
+  resourceName?: string
+  perspective?: PerspectiveHandle['perspective']
+}
+
+/**
+ * SDK React DocumentTypeHandle with optional explicit resource field.
+ * Resource is resolved from context when not provided.
+ * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
+ * if there is a matching resource by that name.
+ * @public
+ */
+export interface DocumentTypeHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends ResourceHandle<TProjectId, TDataset> {
+  documentType: TDocumentType
+  documentId?: string
+  liveEdit?: boolean
+}
+
+/**
+ * SDK React DocumentHandle with optional explicit resource field.
+ * Resource is resolved from context when not provided.
+ * When a `resourceName` is provided, the resource will be resolved from the context using the `ResourcesContext`,
+ * if there is a matching resource by that name.
+ * @public
+ */
+export interface DocumentHandle<
+  TDocumentType extends string = string,
+  TDataset extends string = string,
+  TProjectId extends string = string,
+> extends DocumentTypeHandle<TDocumentType, TDataset, TProjectId> {
+  documentId: string
+}

package/src/context/ComlinkTokenRefresh.test.tsx

@@ -56,7 +56,10 @@ describe('ComlinkTokenRefresh', () => {
       it('should not request new token on 401 if not in dashboard', async () => {
         mockUseAuthState.mockReturnValue({type: AuthStateType.LOGGED_IN})
         const {rerender} = render(
-          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -69,7 +72,10 @@ describe('ComlinkTokenRefresh', () => {
         })
         act(() => {
           rerender(
-            <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+            <ResourceProvider
+              resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+              fallback={null}
+            >
               <ComlinkTokenRefreshProvider>
                 <div>Test</div>
               </ComlinkTokenRefreshProvider>
@@ -92,7 +98,10 @@ describe('ComlinkTokenRefresh', () => {
       it('should initialize useWindowConnection with correct parameters when not in studio mode', () => {
         // Simulate studio mode disabled by default
         render(
-          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -124,7 +133,10 @@ describe('ComlinkTokenRefresh', () => {
         document.body.appendChild(errorContainer)
 
         render(
-          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -138,11 +150,10 @@ describe('ComlinkTokenRefresh', () => {
         expect(mockSetAuthToken).toHaveBeenCalledWith(expect.any(Object), 'new-token')
         expect(mockFetch).toHaveBeenCalledTimes(1)
         expect(mockFetch).toHaveBeenCalledWith('dashboard/v1/auth/tokens/create')
-        // Assert setAuthToken was called with instance matching provider config
+        // Assert setAuthToken was called with a SanityInstance
         const instanceArg = mockSetAuthToken.mock.calls[0][0]
-        expect(instanceArg.config).toEqual(
-          expect.objectContaining({projectId: 'test-project', dataset: 'test-dataset'}),
-        )
+        expect(instanceArg).toHaveProperty('instanceId')
+        expect(instanceArg).toHaveProperty('config')
         // Unauthorized error container should be removed
         expect(document.getElementById('__sanityError')).toBeNull()
       })
@@ -155,7 +166,10 @@ describe('ComlinkTokenRefresh', () => {
         mockFetch.mockResolvedValueOnce({token: null})
 
         render(
-          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>
@@ -177,7 +191,10 @@ describe('ComlinkTokenRefresh', () => {
         mockFetch.mockRejectedValueOnce(new Error('Fetch failed'))
 
         render(
-          <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
+          <ResourceProvider
+            resource={{projectId: 'test-project', dataset: 'test-dataset'}}
+            fallback={null}
+          >
             <ComlinkTokenRefreshProvider>
               <div>Test</div>
             </ComlinkTokenRefreshProvider>

package/src/context/DefaultResourceContext.ts

@@ -0,0 +1,10 @@
+import {type DocumentResource} from '@sanity/sdk'
+import {createContext} from 'react'
+
+/**
+ * Provides the active resource for a subtree.
+ * Set by `ResourceProvider` so hooks resolve the correct project/dataset
+ * without requiring an explicit `resource` option.
+ * @internal
+ */
+export const ResourceContext = createContext<DocumentResource | undefined>(undefined)

package/src/context/PerspectiveContext.ts

@@ -0,0 +1,12 @@
+import {type PerspectiveHandle} from '@sanity/sdk'
+import {createContext} from 'react'
+
+/**
+ * Provides a perspective override for nested subtrees.
+ * Set by `ResourceProvider` so hooks resolve the correct perspective
+ * without requiring an explicit `perspective` option.
+ * @internal
+ */
+export const PerspectiveContext = createContext<PerspectiveHandle['perspective'] | undefined>(
+  undefined,
+)