feat: present a link to add CORS Manage setting when a CORS error occurs (#625)

* feat: present a link to add CORS Manage setting when a CORS error occurs

Author: ryanbonial

apps/kitchensink-react/src/AppRoutes.tsx

@@ -17,8 +17,8 @@ import {ProtectedRoute} from './ProtectedRoute'
 import {DashboardContextRoute} from './routes/DashboardContextRoute'
 import {DashboardWorkspacesRoute} from './routes/DashboardWorkspacesRoute'
 import ExperimentalResourceClientRoute from './routes/ExperimentalResourceClientRoute'
-import {ProjectsRoute} from './routes/ProjectsRoute'
 import {PerspectivesRoute} from './routes/PerspectivesRoute'
+import {ProjectsRoute} from './routes/ProjectsRoute'
 import {ReleasesRoute} from './routes/releases/ReleasesRoute'
 import {UserDetailRoute} from './routes/UserDetailRoute'
 import {UsersRoute} from './routes/UsersRoute'

packages/core/src/_exports/index.ts

@@ -123,6 +123,8 @@ export {resolveProjection} from '../projection/resolveProjection'
 export {type ProjectionValuePending, type ValidProjection} from '../projection/types'
 export {getProjectsState, resolveProjects} from '../projects/projects'
 export {
+  clearQueryError,
+  getQueryErrorState,
   getQueryKey,
   getQueryState,
   parseQueryKey,
@@ -157,6 +159,7 @@ export {
 export {type FetcherStore, type FetcherStoreState} from '../utils/createFetcherStore'
 export {createGroqSearchFilter} from '../utils/createGroqSearchFilter'
 export {defineIntent, type Intent, type IntentFilter} from '../utils/defineIntent'
+export {getCorsErrorProjectId} from '../utils/getCorsErrorProjectId'
 export {CORE_SDK_VERSION} from '../version'
 export {
   getIndexForKey,

packages/core/src/query/queryStore.ts

@@ -1,8 +1,9 @@
-import {type ResponseQueryOptions} from '@sanity/client'
+import {CorsOriginError, type ResponseQueryOptions} from '@sanity/client'
 import {type SanityQueryResult} from 'groq'
 import {
   catchError,
   combineLatest,
+  defer,
   distinctUntilChanged,
   EMPTY,
   filter,
@@ -207,7 +208,18 @@ const listenToLiveClientAndSetLastLiveEventIds = ({
     apiVersion: QUERY_STORE_API_VERSION,
   }).observable.pipe(
     switchMap((client) =>
-      client.live.events({includeDrafts: !!client.config().token, tag: 'query-store'}),
+      defer(() =>
+        client.live.events({includeDrafts: !!client.config().token, tag: 'query-store'}),
+      ).pipe(
+        catchError((error) => {
+          if (error instanceof CorsOriginError) {
+            // Swallow only CORS errors in store without bubbling up so that they are handled by the Cors Error component
+            state.set('setError', {error})
+            return EMPTY
+          }
+          throw error
+        }),
+      ),
     ),
     share(),
     filter((e) => e.type === 'message'),
@@ -305,6 +317,29 @@ const _getQueryState = bindActionByDataset(
   }),
 )
 
+/**
+ * Returns a state source for the top-level query store error (if any).
+ *
+ * Unlike {@link getQueryState}, this selector does not throw; it simply returns the error value.
+ * Subscribe to this to be notified when a global query error occurs (e.g., CORS failures).
+ *
+ * @beta
+ */
+export function getQueryErrorState(instance: SanityInstance): StateSource<unknown | undefined> {
+  return _getQueryErrorState(instance)
+}
+
+const _getQueryErrorState = bindActionByDataset(
+  queryStore,
+  createStateSourceAction({
+    selector: ({state}: SelectorContext<QueryStoreState>) => state.error,
+    onSubscribe: () => {
+      // No-op subscription as we don't track per-query subscribers here
+      return () => {}
+    },
+  }),
+)
+
 /**
  * Resolves the result of a query without registering a lasting subscriber.
  *
@@ -378,3 +413,16 @@ const _resolveQuery = bindActionByDataset(
     return firstValueFrom(race([resolved$, aborted$]))
   },
 )
+
+/**
+ * Clears the top-level query store error.
+ * @beta
+ */
+export function clearQueryError(instance: SanityInstance): void
+export function clearQueryError(...args: Parameters<typeof _clearQueryError>): void {
+  return _clearQueryError(...args)
+}
+
+const _clearQueryError = bindActionByDataset(queryStore, ({state}) => {
+  state.set('setError', {error: undefined})
+})

packages/core/src/utils/getCorsErrorProjectId.test.ts

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {CorsOriginError} from '@sanity/client'
+import {afterEach, describe, expect, test} from 'vitest'
+
+import {getCorsErrorProjectId} from './getCorsErrorProjectId'
+
+describe('getCorsErrorProjectId', () => {
+  const originalLocation = (globalThis as any).location
+
+  afterEach(() => {
+    if (originalLocation === undefined) {
+      delete (globalThis as any).location
+    } else {
+      ;(globalThis as any).location = originalLocation
+    }
+  })
+
+  test('returns null for non-CorsOriginError', () => {
+    const err = new Error(
+      'Change your configuration here: https://sanity.io/manage/project/abc123/api',
+    )
+
+    expect(getCorsErrorProjectId(err)).toBeNull()
+  })
+
+  test('extracts projectId from CorsOriginError in Node environment', () => {
+    delete (globalThis as any).location
+    const err = new CorsOriginError({projectId: 'abc123'})
+
+    expect(getCorsErrorProjectId(err as unknown as Error)).toBe('abc123')
+  })
+
+  test('extracts projectId from CorsOriginError with browser query params', () => {
+    ;(globalThis as any).location = {origin: 'https://example.com'}
+    const err = new CorsOriginError({projectId: 'p123-xyz'})
+
+    expect(getCorsErrorProjectId(err as unknown as Error)).toBe('p123-xyz')
+  })
+
+  test('returns null if CorsOriginError message does not contain manage URL', () => {
+    const err = new CorsOriginError({projectId: 'abc123'})
+    err.message = 'Some other message without the manage URL'
+
+    expect(getCorsErrorProjectId(err as unknown as Error)).toBeNull()
+  })
+})

packages/core/src/utils/getCorsErrorProjectId.ts

@@ -0,0 +1,15 @@
+import {CorsOriginError} from '@sanity/client'
+
+/**
+ * @public
+ * Extracts the project ID from a CorsOriginError message.
+ * @param error - The error to extract the project ID from.
+ * @returns The project ID or null if the error is not a CorsOriginError.
+ */
+export function getCorsErrorProjectId(error: Error): string | null {
+  if (!(error instanceof CorsOriginError)) return null
+
+  const message = (error as unknown as {message?: string}).message || ''
+  const projMatch = message.match(/manage\/project\/([^/?#]+)/)
+  return projMatch ? projMatch[1] : null
+}

packages/react/src/components/auth/AuthBoundary.tsx

@@ -1,11 +1,14 @@
-import {AuthStateType} from '@sanity/sdk'
+import {CorsOriginError} from '@sanity/client'
+import {AuthStateType, getCorsErrorProjectId} from '@sanity/sdk'
 import {useEffect, useMemo} from 'react'
 import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
 
 import {ComlinkTokenRefreshProvider} from '../../context/ComlinkTokenRefresh'
 import {useAuthState} from '../../hooks/auth/useAuthState'
 import {useLoginUrl} from '../../hooks/auth/useLoginUrl'
 import {useVerifyOrgProjects} from '../../hooks/auth/useVerifyOrgProjects'
+import {useCorsOriginError} from '../../hooks/errors/useCorsOriginError'
+import {CorsErrorComponent} from '../errors/CorsErrorComponent'
 import {isInIframe} from '../utils'
 import {AuthError} from './AuthError'
 import {ConfigurationError} from './ConfigurationError'
@@ -105,16 +108,38 @@ export function AuthBoundary({
   LoginErrorComponent = LoginError,
   ...props
 }: AuthBoundaryProps): React.ReactNode {
+  const {error: corsError, projectId, clear: clearCorsError} = useCorsOriginError()
+
   const FallbackComponent = useMemo(() => {
     return function LoginComponentWithLayoutProps(fallbackProps: FallbackProps) {
+      if (fallbackProps.error instanceof CorsOriginError) {
+        return (
+          <CorsErrorComponent
+            {...fallbackProps}
+            projectId={getCorsErrorProjectId(fallbackProps.error)}
+            resetErrorBoundary={() => {
+              clearCorsError()
+              fallbackProps.resetErrorBoundary()
+            }}
+          />
+        )
+      }
       return <LoginErrorComponent {...fallbackProps} />
     }
-  }, [LoginErrorComponent])
+  }, [LoginErrorComponent, clearCorsError])
 
   return (
     <ComlinkTokenRefreshProvider>
       <ErrorBoundary FallbackComponent={FallbackComponent}>
-        <AuthSwitch {...props} />
+        {corsError ? (
+          <CorsErrorComponent
+            error={corsError}
+            resetErrorBoundary={() => clearCorsError()}
+            projectId={projectId}
+          />
+        ) : (
+          <AuthSwitch {...props} />
+        )}
       </ErrorBoundary>
     </ComlinkTokenRefreshProvider>
   )

packages/react/src/components/errors/CorsErrorComponent.test.tsx

@@ -0,0 +1,48 @@
+import {describe, expect, it} from 'vitest'
+
+import {render, screen} from '../../../test/test-utils'
+import {CorsErrorComponent} from './CorsErrorComponent'
+
+describe('CorsErrorComponent', () => {
+  it('shows origin and manage link when projectId is provided', () => {
+    const origin = 'https://example.com'
+    const originalLocation = window.location
+    // Redefine window.location to control origin in this test
+    Object.defineProperty(window, 'location', {
+      value: {origin},
+      configurable: true,
+    })
+
+    render(
+      <CorsErrorComponent
+        projectId="proj123"
+        error={new Error('nope')}
+        resetErrorBoundary={() => {}}
+      />,
+    )
+
+    expect(screen.getByText('Before you continue...')).toBeInTheDocument()
+    expect(screen.getByText(origin)).toBeInTheDocument()
+
+    const link = screen.getByRole('link', {name: 'Manage CORS configuration'}) as HTMLAnchorElement
+    expect(link).toBeInTheDocument()
+    expect(link.target).toBe('_blank')
+    expect(link.rel).toContain('noopener')
+    expect(link.href).toContain('https://sanity.io/manage/project/proj123/api')
+    expect(link.href).toContain('cors=add')
+    expect(link.href).toContain(`origin=${encodeURIComponent(origin)}`)
+    expect(link.href).toContain('credentials=include')
+
+    // restore
+    Object.defineProperty(window, 'location', {value: originalLocation})
+  })
+
+  it('shows error message when projectId is null', () => {
+    const error = new Error('some error message')
+    render(<CorsErrorComponent projectId={null} error={error} resetErrorBoundary={() => {}} />)
+
+    expect(screen.getByText('Before you continue...')).toBeInTheDocument()
+    expect(screen.getByText('some error message')).toBeInTheDocument()
+    expect(screen.queryByRole('link', {name: 'Manage CORS configuration'})).toBeNull()
+  })
+})

packages/react/src/components/errors/CorsErrorComponent.tsx

@@ -0,0 +1,40 @@
+import {useMemo} from 'react'
+import {type FallbackProps} from 'react-error-boundary'
+
+type CorsErrorComponentProps = FallbackProps & {
+  projectId: string | null
+}
+
+export function CorsErrorComponent({projectId, error}: CorsErrorComponentProps): React.ReactNode {
+  const origin = window.location.origin
+  const corsUrl = useMemo(() => {
+    const url = new URL(`https://sanity.io/manage/project/${projectId}/api`)
+    url.searchParams.set('cors', 'add')
+    url.searchParams.set('origin', origin)
+    url.searchParams.set('credentials', 'include')
+    return url.toString()
+  }, [origin, projectId])
+  return (
+    <div className="sc-login-error">
+      <div className="sc-login-error__content">
+        <h1>Before you continue...</h1>
+        <p>
+          To access your content, you need to <b>add the following URL as a CORS origin</b> to your
+          Sanity project.
+        </p>
+        <p>
+          <code>{origin}</code>
+        </p>
+        {projectId ? (
+          <p>
+            <a href={corsUrl ?? ''} target="_blank" rel="noopener noreferrer">
+              Manage CORS configuration
+            </a>
+          </p>
+        ) : (
+          <p>{error?.message}</p>
+        )}
+      </div>
+    </div>
+  )
+}

packages/react/src/hooks/errors/useCorsOriginError.ts

@@ -0,0 +1,22 @@
+import {CorsOriginError} from '@sanity/client'
+import {clearQueryError, getCorsErrorProjectId, getQueryErrorState} from '@sanity/sdk'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+export function useCorsOriginError(): {
+  error: Error | null
+  projectId: string | null
+  clear: () => void
+} {
+  const instance = useSanityInstance()
+  const {getCurrent, subscribe} = useMemo(() => getQueryErrorState(instance), [instance])
+  const error = useSyncExternalStore(subscribe, getCurrent)
+  const clear = useCallback(() => clearQueryError(instance), [instance])
+  const value = useMemo(() => {
+    if (!(error instanceof CorsOriginError)) return {error: null, projectId: null}
+
+    return {error: error as unknown as Error, projectId: getCorsErrorProjectId(error)}
+  }, [error])
+  return useMemo(() => ({...value, clear}), [value, clear])
+}