feat: use perspectives features

sanity-io · Jun 20, 2023 · df48f8f · df48f8f
1 parent 4ac493c
commit df48f8f
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 43 deletions.
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -72,6 +72,10 @@ export interface LiveQueryProviderProps {
     /** @defaultValue true */
     listen?: boolean
   }
+  /** @defaultValue 10000 */
+  refreshInterval?: number
+  /** @defaultValue true */
+  turboSourceMap?: boolean
 }
 
 export function LiveQueryProvider(
@@ -112,6 +116,7 @@ export function getClient({
     dataset,
     apiVersion: '2023-06-20',
     useCdn: true,
+    perspective: 'published',
   })
   if (preview) {
     if (!preview.token) {
@@ -121,6 +126,7 @@ export function getClient({
       token: preview.token,
       useCdn: false,
       ignoreBrowserTokenWarning: true,
+      perspective: 'previewDrafts',
     })
   }
   return client
@@ -192,6 +198,7 @@ export function getClient({
     dataset,
     apiVersion: '2023-06-20',
     useCdn: true,
+    perspective: 'published',
   })
   if (preview) {
     if (!preview.token) {
@@ -201,6 +208,7 @@ export function getClient({
       token: preview.token,
       useCdn: false,
       ignoreBrowserTokenWarning: true,
+      perspective: 'previewDrafts',
     })
   }
   return client
@@ -281,6 +289,7 @@ export function getClient({
     dataset,
     apiVersion: '2023-06-20',
     useCdn: true,
+    perspective: 'published',
   })
   if (preview) {
     if (!preview.token) {
@@ -290,6 +299,7 @@ export function getClient({
       token: preview.token,
       useCdn: false,
       ignoreBrowserTokenWarning: true,
+      perspective: 'previewDrafts',
     })
   }
   return client
@@ -360,6 +370,7 @@ export function getClient({
     dataset,
     apiVersion: '2023-06-20',
     useCdn: true,
+    perspective: 'published',
   })
   if (preview) {
     if (!preview.token) {
@@ -369,6 +380,7 @@ export function getClient({
       token: preview.token,
       useCdn: false,
       ignoreBrowserTokenWarning: true,
+      perspective: 'previewDrafts',
     })
   }
   return client

diff --git a/packages/preview-kit/README.md b/packages/preview-kit/README.md
@@ -247,6 +247,7 @@ export function getClient({
     dataset: 'production',
     apiVersion: '2023-06-20',
     useCdn: true,
+    perspective: 'published',
   })
   if (preview) {
     if (!preview.token) {
@@ -256,6 +257,7 @@ export function getClient({
       token: preview.token,
       useCdn: false,
       ignoreBrowserTokenWarning: true,
+      perspective: 'previewDrafts',
     })
   }
   return client
@@ -386,15 +388,6 @@ import { Layout } from '~/ui'
 
 const PreviewProvider = lazy(() => import('~/PreviewProvider'))
 
-export const getClient = (preview = false) =>
-  createClient({
-    projectId: process.env.SANITY_PROJECT_ID,
-    dataset: process.env.SANITY_DATASET,
-    apiVersion: process.env.SANITY_API_VERSION,
-    useCdn: !preview,
-    token: preview ? process.env.SANITY_API_READ_TOKEN : undefined,
-  })
-
 export async function loader({ request }: LoaderArgs) {
   const token = process.env.SANITY_API_READ_TOKEN
   const preview =
@@ -661,13 +654,55 @@ return (
       // by only including the ones you need.
       includeTypes: ['page', 'product', 'sanity.imageAsset'],
       // Turn off using a mutation EventSource listener, this means content updates will require a manual refresh
-      listen: false
+      listen: false,
     }}
+    // If the cache is full it'll fallback to a polling interval mode, that refreshes every 10 seconds by default.
+    // You can opt-in to having an error thrown instead by setting this to `0`.
+    refreshInterval={10000}
+    // Passing a logger gives you more information on what to expect based on your configuration
+    logger={console}
+  >
+    {children}
+  </LiveQueryProvider>
+)
+```
+
+#### Content Source Map features
+
+When the `client` instance is configured to `client.config().resultSourceMap == true` the `LiveQueryProvider` will opt-in to a faster and smarter cache than the default mode.
+It'll only listen for mutations on the documents that you are using in your queries, and apply the mutations to the cache in real-time.
+This mode is best-effort, and if you're relying on features such as `upper` you may want to disable this mode.
+
+```tsx
+import { LiveQueryProvider } from '@sanity/preview-kit'
+
+return (
+  <LiveQueryProvider
+    client={client}
+    turboSourceMap={false}
+    // Passing a logger gives you more information on what to expect based on your configuration
+    logger={console}
+  >
+    {children}
+  </LiveQueryProvider>
+)
+```
+
+For data that can't be traced with Content Source Maps there's a background refresh interval. Depending on your queries you might want to tweak this interval to get the best performance.
+
+```tsx
+import { LiveQueryProvider } from '@sanity/preview-kit'
+
+return (
+  <LiveQueryProvider
+    client={client}
+    // Refetch all queries every minute instead of the default 10 seconds
+    refreshInterval={1000 * 60}
     // Passing a logger gives you more information on what to expect based on your configuration
     logger={console}
   >
     {children}
-  </GroqStoreProvider>
+  </LiveQueryProvider>
 )
 ```
 

diff --git a/packages/preview-kit/src/LiveQueryProvider.tsx b/packages/preview-kit/src/LiveQueryProvider.tsx
@@ -35,49 +35,37 @@ export interface LiveQueryProviderProps {
   client: SanityClient
   cache?: CacheOptions
   /**
-   * @defaultValue false
-   * @alpha Highly experimental, may have breaking changes in minor releases
+   * Uses a `Listen` API call with EventSource to stream updates in real-time to the documents cache, powered by `Content Source Map` metadata
+   * @defaultValue true
    */
-  experimental__turboSourceMap?: boolean
+  turboSourceMap?: boolean
   /**
    * The interval in millieseconds to refetch in the background, when the tab is active.
+   * It's only used if `turboSourceMap` is set to `true` or there are too many documents to fit in the local cache.
    * Set it to `0` to disable background refresh.
-   * @defaultValue experimental__turboSourceMap ? 10000 : 0
-   * @alpha Highly experimental, may have breaking changes in minor releases
+   * @defaultValue 10000
    */
-  experimental__refreshInterval?: number
+  refreshInterval?: number
   logger?: Logger
 }
 
 export const LiveQueryProvider = memo(function LiveQueryProvider(
   props: LiveQueryProviderProps
 ) {
-  const {
-    children,
-    experimental__turboSourceMap = false,
-    experimental__refreshInterval,
-  } = props
+  const { children, turboSourceMap = true, refreshInterval = 10000 } = props
   // Ensure these values are stable even if userland isn't memoizing properly
   const [client] = useState(() => props.client)
   const [cache] = useState(() => props.cache)
   const [logger] = useState(() => props.logger)
 
-  useEffect(() => {
-    if (experimental__refreshInterval || experimental__turboSourceMap) {
-      logger?.warn(
-        '[@sanity/preview-kit]: You are using experimental features, these may have breaking changes in minor releases'
-      )
-    }
-  }, [experimental__refreshInterval, experimental__turboSourceMap, logger])
-
-  if (experimental__turboSourceMap) {
+  if (turboSourceMap) {
     return (
       <Suspense fallback={children}>
         <LiveStoreProvider
           client={client}
           logger={logger}
-          refreshInterval={experimental__refreshInterval}
-          turboSourceMap={experimental__turboSourceMap}
+          refreshInterval={refreshInterval}
+          turboSourceMap={turboSourceMap}
         >
           {children}
         </LiveStoreProvider>
@@ -90,7 +78,7 @@ export const LiveQueryProvider = memo(function LiveQueryProvider(
       client={client}
       cache={cache}
       logger={logger}
-      experimental__refreshInterval={experimental__refreshInterval}
+      refreshInterval={refreshInterval}
     >
       {children}
     </SelectStoreProvider>
@@ -100,13 +88,7 @@ export const LiveQueryProvider = memo(function LiveQueryProvider(
 const SelectStoreProvider = memo(function SelectStoreProvider(
   props: LiveQueryProviderProps
 ) {
-  const {
-    children,
-    experimental__refreshInterval = 0,
-    client,
-    cache,
-    logger,
-  } = props
+  const { children, refreshInterval, client, cache, logger } = props
   const maxDocuments = cache?.maxDocuments ?? DEFAULT_MAX_DOCUMENTS
   const [documentsCount, setDocumentsCount] = useState<number | null>(null)
   const [error, setError] = useState<Error | null>(null)
@@ -147,12 +129,12 @@ const SelectStoreProvider = memo(function SelectStoreProvider(
     return children
   }
 
-  if (experimental__refreshInterval && documentsCount >= maxDocuments) {
+  if (refreshInterval && documentsCount >= maxDocuments) {
     return (
       <Suspense fallback={children}>
         <LiveStoreProvider
           client={client}
-          refreshInterval={experimental__refreshInterval}
+          refreshInterval={refreshInterval}
           turboSourceMap={false}
           logger={logger}
         >