next-sanity 4.1.0 → 4.1.2

package/README.md

@@ -13,20 +13,21 @@
 - [Table of contents](#table-of-contents)
 - [Installation](#installation)
 - [`next-sanity` Running groq queries](#next-sanity-running-groq-queries)
+  - [`appDir`, React Server Components and caching](#appdir-react-server-components-and-caching)
 - [`next-sanity/preview` Live real-time preview](#next-sanitypreview-live-real-time-preview)
   - [Examples](#examples)
     - [Built-in Sanity auth](#built-in-sanity-auth)
-      - [Next 12](#next-12)
-      - [Next 13 `appDir`](#next-13-appdir)
+      - [Using the `/pages` directory](#using-the-pages-directory)
+      - [Using the `/app` directory (experimental)](#using-the-app-directory-experimental)
     - [Custom token auth](#custom-token-auth)
-      - [Next 12](#next-12-1)
-      - [Next 13 `appDir`](#next-13-appdir-1)
+      - [Using the `/pages` directory](#using-the-pages-directory-1)
+      - [Using the `/app` directory (experimental)](#using-the-app-directory-experimental-1)
   - [Starters](#starters)
   - [Limits](#limits)
 - [`next-sanity/studio`](#next-sanitystudio)
   - [Usage](#usage)
-    - [Next 13 `app/studio`](#next-13-appstudio)
-    - [Next 12 or `pages/studio`](#next-12-or-pagesstudio)
+    - [Using the `/app` directory (experimental)](#using-the-app-directory-experimental-2)
+    - [Using the `/pages` directory](#using-the-pages-directory-2)
   - [Opt-in to using `StudioProvider` and `StudioLayout`](#opt-in-to-using-studioprovider-and-studiolayout)
 - [`next-sanity/webhook`](#next-sanitywebhook)
 - [Migrate](#migrate)
@@ -49,10 +50,34 @@
 
 ## Installation
 
-```sh
-$ npm install next-sanity @portabletext/react @sanity/image-url
-// or
-$ yarn add next-sanity @portabletext/react @sanity/image-url
+```bash
+npm install next-sanity @portabletext/react @sanity/image-url
+```
+
+```bash
+yarn add next-sanity @portabletext/react @sanity/image-url
+```
+
+```bash
+pnpm install next-sanity @portabletext/react @sanity/image-url
+```
+
+### `next-sanity/studio` peer dependencies
+
+When using `npm` newer than `v7` you should end up with needed dependencies like `sanity` and `styled-components` when you `npm install next-sanity`. For other package managers you may need to do some extra steps.
+
+#### Yarn
+
+```bash
+npx install-peerdeps --yarn next-sanity
+```
+
+#### pnpm
+
+You can either setup [`auto-install-peers`](https://stackoverflow.com/questions/72468635/pnpm-peer-dependencies-auto-install/74835069#74835069) and `pnpm install next-sanity` is enough, or:
+
+```bash
+npx install-peerdeps --pnpm next-sanity
 ```
 
 ## `next-sanity` Running groq queries
@@ -74,6 +99,34 @@ const client = createClient({
 const data = await client.fetch(groq`*[]`)
 ```
 
+### `appDir`, React Server Components and caching
+
+As `@sanity/client` will only sometimes use `fetch` under the hood, it depends on the environment, [it's best to implement the cache function to ensure reliable caching.](https://beta.nextjs.org/docs/data-fetching/caching#per-request-cachingmd)
+
+```ts
+import {createClient, groq} from 'next-sanity'
+import {cache} from 'react'
+
+const projectId = process.env.NEXT_PUBLIC_SANITY_PROJECT_ID // "pv8y60vp"
+const dataset = process.env.NEXT_PUBLIC_SANITY_DATASET // "production"
+const apiVersion = process.env.NEXT_PUBLIC_SANITY_API_VERSION // "2022-11-16"
+
+const client = createClient({
+  projectId,
+  dataset,
+  apiVersion, // https://www.sanity.io/docs/api-versioning
+  useCdn: typeof document !== 'undefined', // server-side is statically generated, the CDN is only necessary beneficial if queries are called on-demand
+})
+
+// Wrap the cache function in a way that reuses the TypeScript definitions
+const clientFetch = cache(client.fetch.bind(client))
+
+// Now use it just like before, fully deduped, cached and optimized by react
+const data = await clientFetch(groq`*[]`)
+// You can use the same generics as ebfore
+const total = await clientFetch<number>(groq`count*()`)
+```
+
 ## `next-sanity/preview` Live real-time preview
 
 You can implement real-time client side preview using `definePreview`. It works by streaming the whole dataset to the browser, which it keeps updated using [listeners](https://www.sanity.io/docs/realtime-updates) and Mendoza patches. When it receives updates, then the query is run against the client-side datastore using [groq-js](https://github.com/sanity-io/groq-js).
@@ -99,7 +152,7 @@ Cons:
   - Safari based browsers (Desktop Safari on Macs, and all browsers on iOS) doesn't work.
   - Doesn't support incognito browser modes.
 
-`pages/api/preview.js`:
+`pages/api/preview.ts`:
 
 ```js
 export default function preview(req, res) {
@@ -109,7 +162,7 @@ export default function preview(req, res) {
 }
 ```
 
-`pages/api/exit-preview.js`:
+`pages/api/exit-preview.ts`:
 
 ```js
 export default function exit(req, res) {
@@ -119,9 +172,9 @@ export default function exit(req, res) {
 }
 ```
 
-`components/DocumentsCount.js`:
+`components/DocumentsCount.tsx`:
 
-```jsx
+```tsx
 import groq from 'groq'
 
 export const query = groq`count(*[])`
@@ -135,7 +188,7 @@ export function DocumentsCount({data}) {
 }
 ```
 
-`lib/sanity.client.js`
+`lib/sanity.client.ts`
 
 ```js
 import {createClient} from 'next-sanity'
@@ -147,11 +200,9 @@ const apiVersion = process.env.NEXT_PUBLIC_SANITY_API_VERSION // "2022-11-16"
 export const client = createClient({projectId, dataset, apiVersion, useCdn: false})
 ```
 
-`lib/sanity.preview.js`
+`lib/sanity.preview.ts`
 
 ```js
-'use client'
-
 import {definePreview} from 'next-sanity/preview'
 import {projectId, dataset} from 'lib/sanity.client'
 
@@ -161,9 +212,9 @@ function onPublicAccessOnly() {
 export const usePreview = definePreview({projectId, dataset, onPublicAccessOnly})
 ```
 
-`components/PreviewDocumentsCount.js`:
+`components/PreviewDocumentsCount.ts`:
 
-```jsx
+```tsx
 'use client'
 
 import {usePreview} from 'lib/sanity.preview'
@@ -175,11 +226,11 @@ export default function PreviewDocumentsCount() {
 }
 ```
 
-##### Next 12
+##### Using the `/pages` directory
 
-`pages/index.js`:
+`pages/index.tsx`:
 
-```jsx
+```tsx
 import {PreviewSuspense} from 'next-sanity/preview'
 import {lazy} from 'react'
 import {DocumentsCount, query} from 'components/DocumentsCount'
@@ -210,25 +261,31 @@ export default function IndexPage({preview, data}) {
 }
 ```
 
-##### Next 13 `appDir`
+##### Using the `/app` directory (experimental)
 
-`components/PreviewSuspense.js`:
+We support the new `appDir` mode in Next, [but please note that `appDir` shouldn't be used in production before Vercel says it's stable](https://beta.nextjs.org/docs/getting-started).
 
-```jsx
+`components/PreviewSuspense.tsx`:
+
+```tsx
 'use client'
 
 // Once rollup supports 'use client' module directives then 'next-sanity' will include them and this re-export will no longer be necessary
 export {PreviewSuspense as default} from 'next-sanity/preview'
 ```
 
-`app/page.js`:
+`app/page.tsx`:
 
-```jsx
+```tsx
 import {previewData} from 'next/headers'
 import PreviewSuspense from 'components/PreviewSuspense'
 import {DocumentsCount, query} from 'components/DocumentsCount'
 import PreviewDocumentsCount from 'components/PreviewDocumentsCount'
 import {client} from 'lib/sanity.client'
+import {cache} from 'react'
+
+// Enable NextJS to cache and dedupe queries
+const clientFetch = cache(client.fetch.bind(client))
 
 export default async function IndexPage() {
   if (previewData()) {
@@ -239,7 +296,7 @@ export default async function IndexPage() {
     )
   }
 
-  const data = await client.fetch(query)
+  const data = await clientFetch(query)
   return <DocumentsCount data={data} />
 }
 ```
@@ -261,7 +318,7 @@ Cons:
 - Like all things with great power comes great responsibility. You're responsible for implementing adequate protection against leaking the `token` in your js bundle, or preventing the `/api/preview?secret=${secret}` from being easily guessable.
 - It results in a larger JS bundle as `@sanity/groq-store` currently requires `event-source-polyfill` since native `window.EventSource` does not support setting `Authorization` headers needed for the token auth.
 
-`pages/api/preview.js`:
+`pages/api/preview.ts`:
 
 ```js
 import getSecret from 'lib/getSecret'
@@ -282,7 +339,7 @@ export default async function preview(req, res) {
 }
 ```
 
-`pages/api/exit-preview.js`:
+`pages/api/exit-preview.ts`:
 
 ```js
 export default function exit(req, res) {
@@ -292,9 +349,9 @@ export default function exit(req, res) {
 }
 ```
 
-`components/DocumentsCount.js`:
+`components/DocumentsCount.tsx`:
 
-```jsx
+```tsx
 import groq from 'groq'
 
 export const query = groq`count(*[])`
@@ -308,7 +365,7 @@ export function DocumentsCount({data}) {
 }
 ```
 
-`lib/sanity.client.js`
+`lib/sanity.client.ts`
 
 ```js
 import {createClient} from 'next-sanity'
@@ -320,20 +377,18 @@ const apiVersion = process.env.NEXT_PUBLIC_SANITY_API_VERSION // "2022-11-16"
 export const client = createClient({projectId, dataset, apiVersion, useCdn: false})
 ```
 
-`lib/sanity.preview.js`
+`lib/sanity.preview.ts`
 
 ```js
-'use client'
-
 import {definePreview} from 'next-sanity/preview'
 import {projectId, dataset} from 'lib/sanity.client'
 
 export const usePreview = definePreview({projectId, dataset})
 ```
 
-`components/PreviewDocumentsCount.js`:
+`components/PreviewDocumentsCount.tsx`:
 
-```jsx
+```tsx
 'use client'
 
 import {usePreview} from 'lib/sanity.preview'
@@ -345,16 +400,17 @@ export default function PreviewDocumentsCount({token}) {
 }
 ```
 
-##### Next 12
+##### Using the `/pages` directory
 
-`pages/index.js`:
+`pages/index.tsx`:
 
-```jsx
+```tsx
 import {PreviewSuspense} from 'next-sanity/preview'
 import {lazy} from 'react'
 import {DocumentsCount, query} from 'components/DocumentsCount'
 import {client} from 'lib/sanity.client'
 
+// Wrapping preview components in React.lazy ensures visitors not on preview mode doesn't load any JS related to it
 const PreviewDocumentsCount = lazy(() => import('components/PreviewDocumentsCount'))
 
 export const getStaticProps = async ({preview = false, previewData = {}}) => {
@@ -380,31 +436,34 @@ export default function IndexPage({preview, token, data}) {
 }
 ```
 
-##### Next 13 `appDir`
+##### Using the `/app` directory (experimental)
+
+We support the new `appDir` mode in Next, [but please note that `appDir` shouldn't be used in production before Vercel says it's stable](https://beta.nextjs.org/docs/getting-started).
 
-`components/PreviewSuspense.js`:
+`components/PreviewSuspense.tsx`:
 
-```jsx
+```tsx
 'use client'
 
 // Once rollup supports 'use client' module directives then 'next-sanity' will include them and this re-export will no longer be necessary
 export {PreviewSuspense as default} from 'next-sanity/preview'
 ```
 
-`app/page.js`:
+`app/page.tsx`:
 
-```jsx
+```tsx
 import {previewData} from 'next/headers'
 import PreviewSuspense from 'components/PreviewSuspense'
 import {DocumentsCount, query} from 'components/DocumentsCount'
 import PreviewDocumentsCount from 'components/PreviewDocumentsCount'
 import {client} from 'lib/sanity.client'
 
+type AppPreviewData = {token: string} | undefined
 export default async function IndexPage() {
-  if (previewData()?.token) {
+  if ((previewData() as AppPreviewData)?.token) {
     return (
       <PreviewSuspense fallback="Loading...">
-        <PreviewDocumentsCount token={previewData().token} />
+        <PreviewDocumentsCount token={(previewData() as AppPreviewData).token} />
       </PreviewSuspense>
     )
   }
@@ -456,7 +515,7 @@ The basic setup is 2 components, `NextStudio` and `NextStudioHead`.
 `NextStudio` loads up the `import {Studio} from 'sanity'` component for you and wraps it in a Next-friendly layout.
 While `NextStudioHead` sets necessary `<head>` meta tags such as `<meta name="viewport">` to ensure the responsive CSS in the Studio works as expected.
 
-Both the Next 13 and 12 examples uses this config file:
+Both the Next `/app` and `/pages` examples uses this config file:
 `sanity.config.ts`:
 
 ```ts
@@ -501,9 +560,11 @@ export default defineCliConfig({api: {projectId, dataset}})
 
 Now you can run commands like `npx sanity cors add`. See `npx sanity help` for a full list of what you can do.
 
-#### Next 13 `app/studio`
+#### Using the `/app` directory (experimental)
+
+We support the new `appDir` mode in Next, [but please note that `appDir` shouldn't be used in production before Vercel says it's stable](https://beta.nextjs.org/docs/getting-started).
 
-In Next 13's `appDir` mode you use `page.tsx` to load `NextStudio`, and optionally (recommended, especially if you want great support for iPhones and other devices with display cutouts like "The Notch" or "Dynamic Island") export `NextStudioHead` in a `head.tsx`.
+In Next 13's new `appDir` mode you use `page.tsx` to load `NextStudio`, and optionally (recommended, especially if you want great support for iPhones and other devices with display cutouts like "The Notch" or "Dynamic Island") export `NextStudioHead` in a `head.tsx`.
 In routes that load `NextStudio` ensure you have `'use client'` at the top of your file.
 
 `app/studio/[[...index]]/page.tsx`:
@@ -560,7 +621,7 @@ export default function Loading() {
 }
 ```
 
-#### Next 12 or `pages/studio`
+#### Using the `/pages` directory
 
 Using just `NextStudio` gives you a fully working Sanity Studio v3. However we recommend also using `NextStudioHead` as it ensures CSS Media Queries that target mobile devices with display cutouts (for example iPhone's "The Notch" and "Dynamic Island") and other details.
 
@@ -651,7 +712,7 @@ The `v3` release only contains breaking changes on the `next-sanity/studio` impo
 
 #### `NextStudioGlobalStyle` is removed
 
-The layout is no longer using global CSS to set the Studio height. The switch to local CSS helps interop between Next 12 and 13 layouts.
+The layout is no longer using global CSS to set the Studio height. The switch to local CSS helps interop between Next `/pages` and `/app` layouts.
 
 #### `ServerStyleSheetDocument` is removed
 
@@ -684,7 +745,7 @@ export default function MyComponent(props: Pick<StudioProps, 'config'>) {
 }
 ```
 
-The reason why `useBasePath` and `useConfigWithBasePath` got removed is because Next 12 and 13 diverge too much in how they declare dynamic segments. Thus you'll need to specify `basePath` in your `sanity.config.ts` manually to match the route you're loading the studio, for the time being.
+The reason why `useBasePath` and `useConfigWithBasePath` got removed is because Next `/pages` and `/app` diverge too much in how they declare dynamic segments. Thus you'll need to specify `basePath` in your `sanity.config.ts` manually to match the route you're loading the studio, for the time being.
 
 #### The `NextStudioHead` component has moved from `next-sanity/studio` to `next-sanity/studio/head`
 
@@ -698,11 +759,11 @@ There are several differences between the hooks. First of all, `definePreview` r
 
 ##### Before
 
-The files that are imported here are the same as the [Next 12 example](#next-12).
+The files that are imported here are the same as the [Next `/pages` example](#using-the-pages-director).
 
-`pages/index.js`
+`pages/index.tsx`
 
-```jsx
+```tsx
 import {createPreviewSubscriptionHook} from 'next-sanity'
 import {DocumentsCount, query} from 'components/DocumentsCount'
 import {client, projectId, dataset} from 'lib/sanity.client'
@@ -722,9 +783,9 @@ export default function IndexPage({preview, data: initialData}) {
 
 ##### After
 
-`components/PreviewDocumentsCount.js`
+`components/PreviewDocumentsCount.tsx`
 
-```jsx
+```tsx
 import {definePreview} from 'next-sanity/preview'
 import {projectId, dataset} from 'lib/sanity.client'
 
@@ -735,9 +796,9 @@ export default function PreviewDocumentsCount() {
 }
 ```
 
-`pages/index.js`
+`pages/index.tsx`
 
-```jsx
+```tsx
 import {lazy} from 'react'
 import {PreviewSuspense} from 'next-sanity/preview'
 import {DocumentsCount, query} from 'components/DocumentsCount'
@@ -767,7 +828,7 @@ export default function IndexPage({preview, data}) {
 
 If you used this hook to check if the user is cookie authenticated:
 
-```jsx
+```tsx
 import {createCurrentUserHook} from 'next-sanity'
 
 const projectId = process.env.NEXT_PUBLIC_SANITY_PROJECT_ID
@@ -784,7 +845,7 @@ export default function Page() {
 
 Then you can achieve the same functionality using `@sanity/preview-kit` and `suspend-react`:
 
-```jsx
+```tsx
 import {suspend} from 'suspend-react'
 import {_checkAuth} from '@sanity/preview-kit'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-sanity",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Sanity.io toolkit for Next.js",
   "keywords": [
     "sanity",
@@ -147,46 +147,46 @@
   },
   "dependencies": {
     "@sanity/client": "^4",
-    "@sanity/preview-kit": "^1.2",
+    "@sanity/preview-kit": "^1.3",
     "@sanity/webhook": "^2",
     "groq": "^3"
   },
   "devDependencies": {
     "@rollup/plugin-url": "^8.0.1",
     "@sanity/eslint-config-studio": "^2.0.1",
-    "@sanity/image-url": "^1.0.1",
-    "@sanity/pkg-utils": "^2.2.1",
-    "@sanity/semantic-release-preset": "^3.0.2",
-    "@sanity/ui": "^1.0.14",
-    "@sanity/vision": "^3.2.4",
-    "@types/eventsource": "^1.1.10",
-    "@types/jest": "^29.2.5",
-    "@types/react": "^18.0.26",
+    "@sanity/image-url": "^1.0.2",
+    "@sanity/pkg-utils": "^2.2.3",
+    "@sanity/semantic-release-preset": "^4.0.0",
+    "@sanity/ui": "^1.1.0",
+    "@sanity/vision": "^3.2.5",
+    "@types/eventsource": "^1.1.11",
+    "@types/jest": "^29.4.0",
+    "@types/react": "^18.0.27",
     "@types/react-dom": "^18.0.10",
     "@types/styled-components": "^5.1.26",
-    "@typescript-eslint/eslint-plugin": "^5.48.2",
+    "@typescript-eslint/eslint-plugin": "^5.49.0",
     "autoprefixer": "^10.4.13",
     "eslint": "^8.32.0",
-    "eslint-config-next": "13.1.3-canary.2",
+    "eslint-config-next": "13.1.5",
     "eslint-config-prettier": "^8.6.0",
     "eslint-config-sanity": "^6.0.0",
     "eslint-gitignore": "^0.1.0",
     "eslint-plugin-prettier": "^4.2.1",
     "eslint-plugin-simple-import-sort": "^9.0.0",
-    "groqd": "^0.3.1",
-    "jest": "^29.3.1",
-    "jest-environment-jsdom": "^29.3.1",
-    "ls-engines": "^0.8.0",
-    "next": "13.1.3-canary.2",
+    "groqd": "^0.5.0",
+    "jest": "^29.4.1",
+    "jest-environment-jsdom": "^29.4.1",
+    "ls-engines": "^0.8.1",
+    "next": "13.1.5",
     "postcss": "^8.4.21",
     "prettier": "^2.8.3",
     "prettier-plugin-packagejson": "^2.4.0",
-    "prettier-plugin-tailwindcss": "^0.2.1",
+    "prettier-plugin-tailwindcss": "^0.2.2",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "react-is": "^18.2.0",
-    "rollup": "^3.10.0",
-    "sanity": "^3.2.4",
+    "rollup": "^3.11.0",
+    "sanity": "^3.2.5",
     "styled-components": "^5.3.6",
     "tailwindcss": "^3.2.4",
     "typescript": "^4.9.4",