fix: add release notes

Co-Authored-By: tarungangwani <[email protected]> Co-Authored-By: Martin Jacobsen <[email protected]> Co-Authored-By: even westvang <[email protected]>
sanity-io · May 3, 2023 · 8a401e0 · 8a401e0 · vercel · May 3, 2023
1 parent 0b5b5b3
commit 8a401e0
Show file tree

Hide file tree

Showing 4 changed files with 355 additions and 31 deletions.
diff --git a/packages/preview-kit/CHANGELOG.md b/packages/preview-kit/CHANGELOG.md
@@ -5,6 +5,18 @@
 All notable changes to this project will be documented in this file. See
 [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.5.0](https://github.com/sanity-io/preview-kit/compare/v1.4.1...v1.5.0) (2023-05-03)
+
+### Introducing Content Source Maps
+
+> **Note**
+>
+> Content Source Maps are available for select [Sanity enterprise customers](https://www.sanity.io/enterprise?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch). [Contact our sales team for more information.](https://www.sanity.io/contact/sales?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch)
+
+![](https://i.imgur.com/wt95U5Q.jpg)
+
+Content Source Maps are an optional layer of contextual metadata sent with queries to enable use cases such as [Visual Editing](https://www.sanity.io/blog/visual-editing-sanity-vercel?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch), tracing content lineage, and more. Our implementation of Content Source Maps are based on an [open standard posted on GitHub](https://github.com/sanity-io/content-source-maps), and you can read [the API documentation here](https://#https://www.sanity.io/docs/content-source-maps?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch).
+
 ## [1.4.1](https://github.com/sanity-io/preview-kit/compare/v1.4.0...v1.4.1) (2023-05-03)
 
 ### Bug Fixes

diff --git a/packages/preview-kit/README.md b/packages/preview-kit/README.md
@@ -1,12 +1,10 @@
 # @sanity/preview-kit<!-- omit in toc -->
 
-[Sanity.io](https://www.sanity.io/?utm_source=github&utm_medium=readme&utm_campaign=preview-kit) toolkit for building live-as-you-type content preview experiences.
-Write GROQ queries like [@sanity/client](https://github.com/sanity-io/client) and have them resolve in-memory, locally. Updates from Content Lake are streamed in real-time with sub-second latency.
-
-Requires React 18, support for other libraries like Solid, Svelte, Vue etc are planned. For now you can use [@sanity/groq-store](https://github.com/sanity-io/groq-store) [directly](https://github.com/sanity-io/groq-store/blob/main/example/example.ts).
+[Sanity.io](https://www.sanity.io/?utm_source=github&utm_medium=readme&utm_campaign=preview-kit) toolkit for building live-as-you-type content preview experiences and visual editing.
 
 - [Installation](#installation)
-- [Usage](#usage)
+- [`@sanity/preview-kit/client` Visual Editing with Content Source Maps](#sanitypreview-kitclient)
+- [`@sanity/preview-kit` Live real-time preview for React](#sanitypreview-kit)
   - [Demos \& Starters](#demos--starters)
   - [Remix, cookie auth only](#remix-cookie-auth-only)
   - [Next `/pages` Preview Mode, cookie auth only](#next-pages-preview-mode-cookie-auth-only)
@@ -30,7 +28,191 @@ pnpm i @sanity/preview-kit
 yarn add @sanity/preview-kit
 ```
 
-# Usage
+# `@sanity/preview-kit/client`
+
+## Visual Editing with Content Source Maps
+
+> **Note**
+>
+> [Content Source Maps][content-source-maps-intro] are available [as an API][content-source-maps] for select [Sanity enterprise customers][enterprise-cta]. [Contact our sales team for more information.][sales-cta]
+
+You can use [visual editing][visual-editing-intro] with any framework, not just React. [Read our guide for how to get started.][visual-editing]
+
+### `createClient`
+
+The Preview Kit client is built on top of `@sanity/client` and is designed to be a drop-in replacement. It extends the client configuration with options for customizing visual editing experiences.
+
+```diff
+-import {createClient, type ClientConfig} from '@sanity/client'
++import { createClient, type ClientConfig } from '@sanity/preview-kit/client'
+
+const config: ClientConfig = {
+  projectId: 'your-project-id',
+  dataset: 'your-dataset-name',
+  useCdn: true, // set to `false` to bypass the edge cache
+  apiVersion: '2023-05-03', // use current date (YYYY-MM-DD) to target the latest API version
+
+- // enable content source map in the response
+- resultSourceMap: true,
++ // Required, set it to the URL of your Sanity Studio
++ studioUrl: 'https://your-project-name.sanity.studio',
++ // enable content source map in the response, and encode it into strings
++ // 'auto' is the default, you can also use `true` or `false`
++ encodeSourceMap: 'auto',
+}
+
+const client = createClient(config)
+```
+
+#### `studioUrl`
+
+It's **required**, and can either be an absolute URL:
+
+```ts
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  studioUrl: 'https://your-company.com/studio',
+})
+```
+
+Or a relative path if the Studio is hosted on the same deployment, or embedded in the same app:
+
+```ts
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  studioUrl: '/studio',
+})
+```
+
+#### `encodeSourceMap`
+
+Accepts `"auto"`, the default, or a `boolean`. Controls when to encode the content source map into strings using `@vercel/stega` encoding. When `"auto"` is used a best-effort environment detection is used to see if the environment is a Vercel Preview deployment. Most of the time it works out of the box, but in some scenarios and some frameworks it might be necessary to run custom logic, equivalent to:
+
+```tsx
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  encodeSourceMap: process.env.VERCEL_ENV === 'preview',
+})
+```
+
+#### `encodeSourceMapAtPath`
+
+By default source maps are encoded into all strings that can be traced back to a document field. We make some exceptions for fields like, `document._type`, `document._id` and `document.slug.current`, that we've seen leading to breakage if the string is altered.
+
+You can customize this behavior using `encodeSourceMapAtPath`:
+
+```tsx
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  encodeSourceMapAtPath: (props) => {
+    if (props.path[0] === 'externalUrl') {
+      return false
+    }
+    // The default behavior is packaged into `filterDefault`, allowing you enable encoding fields that are skipped by default
+    return props.filterDefault(props)
+  },
+})
+```
+
+#### `logger`
+
+Pass a `console` into `logger` to get detailed debug info and reports on which fields are encoded and which are skipped:
+
+```tsx
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  logger: console,
+})
+```
+
+An example report:
+
+```bash
+[@sanity/preview-kit]: Creating source map enabled client
+[@sanity/preview-kit]: Stega encoding source map into result
+  [@sanity/preview-kit]: Paths encoded: 3, skipped: 17
+  [@sanity/preview-kit]: Table of encoded paths
+  ┌─────────┬──────────────────────────────────┬───────────────────────────┬────────┐
+  │ (index) │                     path         │           value           │ length │
+  ├─────────┼──────────────────────────────────┼───────────────────────────┼────────┤
+  │    0    │ ["footer",0,"children",0,"text"] │ '"The future is alrea...' │   67   │
+  │    1    │ ["footer",1,"children",0,"text"] │     'Robin Williams'      │   14   │
+  │    2    │             ["title"]            │     'Visual Editing'      │   14   │
+  └─────────┴──────────────────────────────────┴───────────────────────────┴────────┘
+  [@sanity/preview-kit]: List of skipped paths [
+    [ 'footer', number, '_key' ],
+    [ 'footer', number, 'children', number, '_key' ],
+    [ 'footer', number, 'children', number, '_type' ],
+    [ 'footer', number, '_type' ],
+    [ 'footer', number, 'style' ],
+    [ '_type' ],
+    [ 'slug', 'current' ],
+  ]
+```
+
+#### `resultSourceMap`
+
+This option is always enabled if `encodeSourceMap`. It's exposed here to be [compatible with `@sanity/client`](https://github.com/sanity-io/client/#get-started-with-content-source-maps) and custom use cases where you want content source maps, but not the encoding.
+
+```ts
+const client = createClient({
+  ...config,
+  // This option can only enable content source maps, not disable it when `encodeSourceMap` resolves to `true`
+  resultSourceMap: true,
+})
+
+const { result, resultSourceMap } = await client.fetch(query, params, {
+  filterResponse: false,
+})
+
+console.log(resultSourceMap) // `resultSourceMap` is now available, even if `encodeSourceMap` is `false`
+```
+
+## Using the Content Source Map with custom logic
+
+If you're building your own custom preview logic you can use `mapToEditLinks` to skip encoding hidden metadata into strings, and access the edit links directly:
+
+```tsx
+import { createClient } from '@sanity/preview-kit/client'
+
+const client = createClient({
+  ...config,
+  resultSourceMap: true, // Tells Content Lake to include content source maps in the response
+  encodeSourceMap: false, // Disable the default encoding behavior
+})
+
+// const result = await client.fetch(query, params)
+const { result, resultSourceMap } = await client.fetch(
+  query,
+  params,
+  { filterResponse: false } // This option is returns the entire API response instead of selecting just `result`
+)
+const studioUrl = 'https://your-company.com/studio'
+const editLinks = mapToEditLinks({ result, resultSourceMap }, studioUrl)
+
+const title = result.title
+const titleEditLink = editLinks.title
+
+console.log(title, titleEditLink)
+```
+
+# `@sanity/preview-kit`
+
+## Live real-time preview for React
+
+Write GROQ queries like [@sanity/client](https://github.com/sanity-io/client) and have them resolve in-memory, locally. Updates from Content Lake are streamed in real-time with sub-second latency.
+
+Requires React 18, support for other libraries like Solid, Svelte, Vue etc are planned. For now you can use [@sanity/groq-store](https://github.com/sanity-io/groq-store) [directly](https://github.com/sanity-io/groq-store/blob/main/example/example.ts).
 
 You create a `usePreview` hook using `definePreview`
 
@@ -97,7 +279,7 @@ export const loader = async () => {
   const client = createClient({
     projectId,
     dataset,
-    apiVersion: '2022-11-15',
+    apiVersion: '2023-05-03',
     useCdn: true,
   })
 
@@ -367,6 +549,129 @@ export default function PreviewDataTable({ token }) {
 }
 ```
 
+## Create React App, cookie auth only
+
+If you're hosting Sanity Studio on the same domain as you're doing previews, you may use `cookie` based auth:
+
+```jsx
+import createClient from '@sanity/client'
+import { definePreview } from '@sanity/preview-kit'
+import groq from 'groq'
+import { Suspense, useReducer } from 'react'
+import { createRoot } from 'react-dom/client'
+import useSWR from 'swr/immutable'
+
+const root = createRoot(document.getElementById('root'))
+root.render(
+  <Suspense fallback="Loading...">
+    <App />
+  </Suspense>
+)
+
+const projectId = process.env.REACT_APP_SANITY_PROJECT_ID
+const dataset = process.env.REACT_APP_SANITY_DATASET
+const apiVersion = process.env.REACT_APP_SANITY_API_VERSION
+const client = createClient({ projectId, dataset, apiVersion, useCdn: true })
+
+const query = groq`count(*[])`
+
+function App() {
+  const [preview, toggle] = useReducer((state) => !state, false)
+  const { data } = useSWR(query, (query) => client.fetch(query), {
+    suspense: true,
+  })
+
+  return (
+    <>
+      <button type="button" onClick={toggle}>
+        {preview ? 'Stop preview' : 'Start preview'}
+      </button>
+      {preview ? <PreviewCount /> : <Count data={data} />}
+    </>
+  )
+}
+
+const Count = ({ data }) => (
+  <>
+    Documents: <strong>{data}</strong>
+  </>
+)
+
+const usePreview = definePreview({
+  projectId,
+  dataset,
+  onPublicAccessOnly: () =>
+    alert('You are not logged in. You will only see public data.'),
+})
+const PreviewCount = () => {
+  const data = usePreview(null, query)
+
+  return <Count data={data} />
+}
+```
+
+## Create React App, custom token auth
+
+If you're not hosting Sanity Studio on the same domain as your previews, or if you need to support browsers that don't work with cookie auth (iOS Safari or browser incognito modes), you may use the `token` option to provide a Sanity Viewer token:
+
+```jsx
+import createClient from '@sanity/client'
+import { definePreview } from '@sanity/preview-kit'
+import groq from 'groq'
+import { Suspense, useReducer } from 'react'
+import { createRoot } from 'react-dom/client'
+import useSWR from 'swr/immutable'
+
+const root = createRoot(document.getElementById('root'))
+root.render(
+  <Suspense fallback="Loading...">
+    <App />
+  </Suspense>
+)
+
+const projectId = process.env.REACT_APP_SANITY_PROJECT_ID
+const dataset = process.env.REACT_APP_SANITY_DATASET
+const apiVersion = process.env.REACT_APP_SANITY_API_VERSION
+const client = createClient({ projectId, dataset, apiVersion, useCdn: true })
+
+const query = groq`count(*[])`
+
+function App() {
+  const [preview, toggle] = useReducer((state) => !state, false)
+  const { data } = useSWR(query, (query) => client.fetch(query), {
+    suspense: true,
+  })
+
+  return (
+    <>
+      <button type="button" onClick={toggle}>
+        {preview ? 'Stop preview' : 'Start preview'}
+      </button>
+      {preview ? <PreviewCount /> : <Count data={data} />}
+    </>
+  )
+}
+
+const Count = ({ data }) => (
+  <>
+    Documents: <strong>{data}</strong>
+  </>
+)
+
+const usePreview = definePreview({ projectId, dataset })
+const PreviewCount = () => {
+  // Call custom authenticated backend to fetch the Sanity Viewer token
+  const { data: token } = useSWR(
+    'https://example.com/preview/token',
+    (url) => fetch(url, { credentials: 'include' }).then((res) => res.text()),
+    { suspense: true }
+  )
+  const data = usePreview(token, query)
+
+  return <Count data={data} />
+}
+```
+
 # Development
 
 If you have access to the [test studio](https://preview-kit-test-studio.sanity.build) and our Vercel Team, then:
@@ -392,3 +697,10 @@ Semantic release will only release on configured branches, so it is safe to run
 # License
 
 MIT-licensed. See [LICENSE](LICENSE).
+
+[visual-editing]: https://www.sanity.io/docs/vercel-visual-editing?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[visual-editing-intro]: https://www.sanity.io/blog/visual-editing-sanity-vercel?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[content-source-maps]: https://www.sanity.io/docs/content-source-maps?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[content-source-maps-intro]: https://www.sanity.io/blog/content-source-maps-announce?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[sales-cta]: https://www.sanity.io/contact/sales?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
+[enterprise-cta]: https://www.sanity.io/enterprise?utm_source=github.com&utm_medium=referral&utm_campaign=may-vercel-launch
diff --git a/packages/preview-kit/package.json b/packages/preview-kit/package.json
@@ -72,7 +72,7 @@
     "coverage": "vitest run --coverage",
     "lint": "eslint --max-warnings 0 .",
     "prepublishOnly": "pnpm run build",
-    "release": "semantic-release --dry-run --debug || semantic-release --dry-run --debug",
+    "release": "semantic-release || semantic-release --dry-run --debug",
     "test": "vitest",
     "pretest:esm": "pnpm run build",
     "test:esm": "node test.mjs && node test.cjs"