@sanity/cli 8.13.1 → 8.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/cli",
-  "version": "8.13.1",
+  "version": "8.14.0",
   "description": "Sanity CLI tool for managing Sanity projects and organizations",
   "keywords": [
     "cli",
@@ -62,7 +62,7 @@
     "@oclif/core": "^4.11.14",
     "@oclif/plugin-help": "^6.2.53",
     "@oclif/plugin-not-found": "^3.2.88",
-    "@sanity/cli-build": "^6.4.2",
+    "@sanity/cli-build": "^6.4.4",
     "@sanity/cli-core": "^3.8.2",
     "@sanity/client": "^8.6.2",
     "@sanity/codegen": "^8.1.0",
@@ -77,7 +77,7 @@
     "@sanity/telemetry": "^1.1.0",
     "@sanity/template-validator": "^3.1.1",
     "@sanity/types": "^6.15.0",
-    "@sanity/workbench-cli": "^2.8.1",
+    "@sanity/workbench-cli": "^2.8.3",
     "@sanity/worker-channels": "^2.0.0",
     "@sanity/workflow-cli": "0.32.0",
     "@sanity/workflow-engine": "0.32.0",
@@ -116,7 +116,7 @@
     "tinyglobby": "^0.2.17",
     "typeid-js": "^1.2.0",
     "valibot": "^1.4.2",
-    "vite": "^8.3.0",
+    "vite": "^8.3.2",
     "which": "^6.0.1",
     "wrap-ansi": "^9.0.2",
     "yaml": "^2.9.0",
@@ -147,7 +147,7 @@
     "jsdom": "^29.1.1",
     "nock": "^14.0.15",
     "oclif": "^4.23.27",
-    "oxc-transform-react": "^0.147.0",
+    "oxc-transform-react": "^0.152.0",
     "publint": "^0.3.21",
     "rimraf": "^6.0.1",
     "sanity": "^6.15.0",

package/templates/app-sanity-ui/src/App.tsx

@@ -4,6 +4,14 @@ import {Flex, Spinner} from '@sanity/ui'
 import {ExampleComponent} from './ExampleComponent'
 import {SanityUI} from './SanityUI'
 
+function Loading() {
+  return (
+    <Flex justify="center" align="center" height="fill">
+      <Spinner />
+    </Flex>
+  )
+}
+
 function App() {
   // apps can access many different projects or other sources of data
   const sanityConfigs: SanityConfig[] = [
@@ -13,14 +21,6 @@ function App() {
     },
   ]
 
-  function Loading() {
-    return (
-      <Flex justify="center" align="center" width="100vw" height="fill">
-        <Spinner />
-      </Flex>
-    )
-  }
-
   return (
     <SanityUI>
       <SanityApp config={sanityConfigs} fallback={<Loading />}>

package/templates/app-sanity-ui/src/ExampleComponent.tsx

@@ -10,7 +10,7 @@ export function ExampleComponent() {
         <Flex align="center" direction="column" gap={5} marginY={4}>
           <Avatar size={3} src={user?.profileImage} />
           <Heading as="h1">Welcome to your Sanity App, {user?.name}!</Heading>
-          <Stack space={4}>
+          <Stack gap={4}>
             <Text muted>
               This is an example component, rendered with Sanity UI and the{' '}
               <code>useCurrentUser</code> hook from the Sanity App SDK. You can import and use any

package/templates/app-sanity-ui/src/SanityUI.tsx

@@ -1,5 +1,7 @@
-import {ThemeProvider, ToastProvider} from '@sanity/ui'
+import '@sanity/ui/styles.css'
+import {ThemeProvider} from '@sanity/ui'
 import {buildTheme} from '@sanity/ui/theme'
+import {ToastProvider} from '@sanity/ui/toast'
 import {createGlobalStyle} from 'styled-components'
 
 const theme = buildTheme()

package/templates/shared/dashboard/app-quickstart/.claude/skills/sanity-app-sdk/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: sanity-app-sdk
+description: Build features with the Sanity App SDK (@sanity/sdk-react). Use when adding components, fetching or editing Sanity content, or working with hooks like useDocuments, useDocument, useDocumentProjection, useEditDocument, or useQuery.
+---
+
+# Sanity App SDK
+
+## Get the maintained guide first
+
+If the Sanity MCP server is configured, call its `get_sanity_rules` tool with the `app-sdk` rule before writing SDK code. That rule is maintained by Sanity, is more detailed, and supersedes the notes below. The notes below are a fallback for when MCP is not available.
+
+## Picking a hook
+
+- `useDocuments` / `usePaginatedDocuments`: lists of documents. Returns document handles, not full documents.
+- `useDocumentProjection`: read specific fields from a handle, for display.
+- `useDocument` plus `useEditDocument`: read and write a single document in real time.
+- `useQuery`: raw GROQ. Use sparingly; prefer handles plus projections.
+
+## Document handles
+
+Fetch handles first, then spread them into other hooks:
+
+```tsx
+const {data} = useDocuments({documentType: 'article'})
+
+// in a child component receiving one handle:
+const {data: fields} = useDocumentProjection({...handle, projection: '{title}'})
+```
+
+Use `documentId` as the React key when rendering lists, never the array index.
+
+## Suspense
+
+Data hooks suspend while loading. Wrap every data-fetching component in `<Suspense>` with a fallback, keep one fetching hook per component, and always pass a `fallback` to `SanityApp`. All SDK hooks must be used inside `SanityApp`.
+
+## Editing
+
+Write through `useEditDocument` on change so content stays in sync with the Content Lake:
+
+```tsx
+const {data: title} = useDocument({...handle, path: 'title'})
+const editTitle = useEditDocument({...handle, path: 'title'})
+// <input value={title ?? ''} onChange={(e) => editTitle(e.currentTarget.value)} />
+```
+
+Do not hold document field values in `useState` and save on submit. That pattern goes stale and loses concurrent edits.
+
+## Dashboard hooks
+
+This app runs in the Sanity Dashboard (`defineApplication` in `sanity.cli.ts`). Hooks that talk to the Dashboard itself are imported from `@sanity/sdk-react/dashboard`, not `@sanity/sdk-react`:
+
+- `useNavigate`: keep the app's router in sync with the Dashboard URL.
+- `useOrganizationId`: the organization selected in the Dashboard.
+- `useApplications` / `useApplication`: apps available in the Dashboard.
+- `useWindowTitle`: set the browser tab title.
+- `useNavigateToStudioDocument`: open a document in its Studio.
+
+## Documentation
+
+Fetch these for current detail rather than relying on the notes above:
+
+- Best practices: https://www.sanity.io/docs/app-sdk/sdk-best-practices
+- Editing documents: https://www.sanity.io/docs/app-sdk/editing-documents
+- Configuration: https://www.sanity.io/docs/app-sdk/sdk-configuration
+- Deployment: https://www.sanity.io/docs/app-sdk/sdk-deployment
+- API reference with current signatures: https://reference.sanity.io/_sanity/sdk-react/

package/templates/shared/dashboard/app-quickstart/AGENTS.md

@@ -0,0 +1,61 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+A React application built with the Sanity App SDK (`@sanity/sdk-react`). It is not a Sanity Studio. The app reads and writes content in a Sanity project through SDK hooks, and runs inside the organization's Sanity Dashboard, in development and when deployed. The `sanity` CLI runs it with Vite under the hood.
+
+The app is set up for the Sanity Dashboard beta: `sanity.cli.ts` declares it with `defineApplication`.
+
+## Key files
+
+- `src/App.tsx`: entry point. The `SanityApp` component takes a `config` array with `projectId` and `dataset`. All SDK hooks must be used inside `SanityApp`.
+- `sanity.cli.ts`: CLI config. `app` is `defineApplication({title, slug, organizationId, entry})`. `slug` is the app's unique address in the organization, used to create the app on its first deploy: lowercase letters, numbers and hyphens, starting with a letter.
+
+## Commands
+
+- `npm run dev`: starts a local Sanity Dashboard on port 3333 and serves the app on the next port (3334), loaded into that Dashboard. The CLI prints the local Dashboard URL. The app only renders inside the Dashboard, and viewing it requires a signed-in Sanity account, so a human must complete authentication in the browser.
+- `npm run build`: production build.
+- `npm run deploy`: deploy to the organization's Sanity Dashboard.
+
+Environment variables prefixed with `SANITY_APP_` are bundled into the app.
+
+## Deploying without prompts
+
+The first deploy creates the app from `slug` and `title` in `defineApplication`. Do not pass `--create`; it is rejected for this config.
+
+```bash
+npm run deploy -- --yes --json
+```
+
+`--title` overrides `app.title`. Add `--dry-run` to preview the deployment without creating or uploading anything. A first deploy cannot use `--no-build`, because the new app ID is built into the bundle.
+
+Save `application.id` from the JSON response as `deployment.appId` in `sanity.cli.ts`. Later deploys use the same command and update that app. Without `deployment.appId`, a later deploy fails because the slug is already taken; the error includes the app ID to save.
+
+A deployed app is served at `https://<organizationId>.sanity.run/applications/<appId>`.
+
+Agent terminals may disable interactive prompts even with a PTY (`TERM=dumb`). Use these flags rather than changing terminal settings or calling the applications API directly. Run `npm run deploy -- --help` to check which flags the installed CLI supports.
+
+This app is not a Studio. For a Studio's first hosted deployment, use `sanity deploy --url <hostname> --yes`; `studioHost`, if used in config, belongs at the top level, not inside `deployment`.
+
+## Working with the App SDK
+
+If the Sanity MCP server is available, call its `get_sanity_rules` tool with the `app-sdk` rule before writing SDK code. That rule is the maintained guide and supersedes the notes below.
+
+Essentials:
+
+- Data hooks suspend while loading. Wrap every data-fetching component in `<Suspense>`, keep one fetching hook per component, and always pass a `fallback` to `SanityApp`.
+- Fetch lists with `useDocuments` (or `usePaginatedDocuments`). They return document handles, not full documents. Spread a handle into `useDocumentProjection` to display fields, or into `useDocument` and `useEditDocument` for real-time editing.
+- Use `documentId` as the React key when rendering document lists, never the array index.
+- Do not hold document field values in `useState` and save on submit. Write through `useEditDocument` on change so content stays in sync with the Content Lake.
+- Prefer handles plus projections over raw GROQ. Reach for `useQuery` only when a complex query genuinely needs it.
+- Hooks that talk to the Dashboard itself are imported from `@sanity/sdk-react/dashboard`, not `@sanity/sdk-react`. Examples: `useNavigate`, `useOrganizationId`, `useApplications`, `useApplication`, `useWindowTitle`, `useNavigateToStudioDocument`.
+
+## Documentation
+
+- App SDK docs: https://www.sanity.io/docs/app-sdk
+- Best practices: https://www.sanity.io/docs/app-sdk/sdk-best-practices
+- Editing documents: https://www.sanity.io/docs/app-sdk/editing-documents
+- Configuration: https://www.sanity.io/docs/app-sdk/sdk-configuration
+- API reference with current signatures: https://reference.sanity.io/_sanity/sdk-react/

package/templates/shared/dashboard/app-quickstart/README.md

@@ -0,0 +1,30 @@
+# Sanity App
+
+A custom application built with the [Sanity App SDK](https://www.sanity.io/docs/app-sdk?utm_source=readme). It is a React app that runs inside your organization's Sanity Dashboard, in development and when deployed.
+
+This app is set up for the Sanity Dashboard beta: `sanity.cli.ts` declares it with `defineApplication`.
+
+## Commands
+
+- `npm run dev` starts a local Sanity Dashboard (by default at http://localhost:3333, with the app on port 3334) and loads your app into it. Open it and sign in with your Sanity account.
+- `npm run build` builds the app for production.
+- `npm run deploy` deploys the app to your organization's Sanity Dashboard. The first deploy creates the app.
+
+## Configuration
+
+- `src/App.tsx` is the app entry point. The `SanityApp` config sets which project and dataset the app reads content from.
+- `sanity.cli.ts` declares the app with `defineApplication`:
+  - `title`: the app's name in the Dashboard.
+  - `slug`: the app's unique address in your organization, used to create the app on its first deploy. Lowercase letters, numbers and hyphens, starting with a letter.
+  - `organizationId`: the organization the app belongs to.
+  - `entry`: the app entry path.
+
+After the first deploy, add the app ID it prints to `sanity.cli.ts` as `deployment.appId` so later deploys update the same app.
+
+## Learn more
+
+- [App SDK Quickstart Guide](https://www.sanity.io/docs/app-sdk/sdk-quickstart?utm_source=readme)
+- [App SDK documentation](https://www.sanity.io/docs/app-sdk?utm_source=readme)
+- [API reference](https://reference.sanity.io/_sanity/sdk-react/)
+- [Deploying your app](https://www.sanity.io/docs/app-sdk/sdk-deployment?utm_source=readme)
+- [SDK Explorer with example apps](https://sdk-explorer.sanity.io)

package/templates/shared/dashboard/app-sanity-ui/.claude/skills/sanity-app-sdk/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sanity-app-sdk
+description: Build features with the Sanity App SDK (@sanity/sdk-react) and Sanity UI. Use when adding components, fetching or editing Sanity content, or working with hooks like useDocuments, useDocument, useDocumentProjection, useEditDocument, or useQuery.
+---
+
+# Sanity App SDK
+
+## Get the maintained guide first
+
+If the Sanity MCP server is configured, call its `get_sanity_rules` tool with the `app-sdk` rule before writing SDK code. That rule is maintained by Sanity, is more detailed, and supersedes the notes below. The notes below are a fallback for when MCP is not available.
+
+## Picking a hook
+
+- `useDocuments` / `usePaginatedDocuments`: lists of documents. Returns document handles, not full documents.
+- `useDocumentProjection`: read specific fields from a handle, for display.
+- `useDocument` plus `useEditDocument`: read and write a single document in real time.
+- `useQuery`: raw GROQ. Use sparingly; prefer handles plus projections.
+
+## Document handles
+
+Fetch handles first, then spread them into other hooks:
+
+```tsx
+const {data} = useDocuments({documentType: 'article'})
+
+// in a child component receiving one handle:
+const {data: fields} = useDocumentProjection({...handle, projection: '{title}'})
+```
+
+Use `documentId` as the React key when rendering lists, never the array index.
+
+## Suspense
+
+Data hooks suspend while loading. Wrap every data-fetching component in `<Suspense>` with a fallback, keep one fetching hook per component, and always pass a `fallback` to `SanityApp`. All SDK hooks must be used inside `SanityApp`.
+
+## Editing
+
+Write through `useEditDocument` on change so content stays in sync with the Content Lake:
+
+```tsx
+const {data: title} = useDocument({...handle, path: 'title'})
+const editTitle = useEditDocument({...handle, path: 'title'})
+// <input value={title ?? ''} onChange={(e) => editTitle(e.currentTarget.value)} />
+```
+
+Do not hold document field values in `useState` and save on submit. That pattern goes stale and loses concurrent edits.
+
+## Sanity UI
+
+This app wraps everything in Sanity UI's `ThemeProvider` (see `src/SanityUI.tsx`, built with `buildTheme()`). Build UI with Sanity UI primitives like `Card`, `Stack`, `Flex`, `Text`, and `Button`. See https://www.sanity.io/docs/app-sdk/sanity-ui-sdk and https://www.sanity.io/ui.
+
+## Dashboard hooks
+
+This app runs in the Sanity Dashboard (`defineApplication` in `sanity.cli.ts`). Hooks that talk to the Dashboard itself are imported from `@sanity/sdk-react/dashboard`, not `@sanity/sdk-react`:
+
+- `useNavigate`: keep the app's router in sync with the Dashboard URL.
+- `useOrganizationId`: the organization selected in the Dashboard.
+- `useApplications` / `useApplication`: apps available in the Dashboard.
+- `useWindowTitle`: set the browser tab title.
+- `useNavigateToStudioDocument`: open a document in its Studio.
+
+## Documentation
+
+Fetch these for current detail rather than relying on the notes above:
+
+- Best practices: https://www.sanity.io/docs/app-sdk/sdk-best-practices
+- Editing documents: https://www.sanity.io/docs/app-sdk/editing-documents
+- Configuration: https://www.sanity.io/docs/app-sdk/sdk-configuration
+- Deployment: https://www.sanity.io/docs/app-sdk/sdk-deployment
+- API reference with current signatures: https://reference.sanity.io/_sanity/sdk-react/

package/templates/shared/dashboard/app-sanity-ui/AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## What this is
+
+A React application built with the Sanity App SDK (`@sanity/sdk-react`) and Sanity UI (`@sanity/ui`). It is not a Sanity Studio. The app reads and writes content in a Sanity project through SDK hooks, and runs inside the organization's Sanity Dashboard, in development and when deployed. The `sanity` CLI runs it with Vite under the hood.
+
+The app is set up for the Sanity Dashboard beta: `sanity.cli.ts` declares it with `defineApplication`.
+
+## Key files
+
+- `src/App.tsx`: entry point. The `SanityApp` component takes a `config` array with `projectId` and `dataset`. All SDK hooks must be used inside `SanityApp`.
+- `src/SanityUI.tsx`: wraps the app in Sanity UI's `ThemeProvider` with a theme from `buildTheme()`. Sanity UI components must render inside this provider.
+- `sanity.cli.ts`: CLI config. `app` is `defineApplication({title, slug, organizationId, entry})`. `slug` is the app's unique address in the organization, used to create the app on its first deploy: lowercase letters, numbers and hyphens, starting with a letter.
+
+## Commands
+
+- `npm run dev`: starts a local Sanity Dashboard on port 3333 and serves the app on the next port (3334), loaded into that Dashboard. The CLI prints the local Dashboard URL. The app only renders inside the Dashboard, and viewing it requires a signed-in Sanity account, so a human must complete authentication in the browser.
+- `npm run build`: production build.
+- `npm run deploy`: deploy to the organization's Sanity Dashboard.
+
+Environment variables prefixed with `SANITY_APP_` are bundled into the app.
+
+## Deploying without prompts
+
+The first deploy creates the app from `slug` and `title` in `defineApplication`. Do not pass `--create`; it is rejected for this config.
+
+```bash
+npm run deploy -- --yes --json
+```
+
+`--title` overrides `app.title`. Add `--dry-run` to preview the deployment without creating or uploading anything. A first deploy cannot use `--no-build`, because the new app ID is built into the bundle.
+
+Save `application.id` from the JSON response as `deployment.appId` in `sanity.cli.ts`. Later deploys use the same command and update that app. Without `deployment.appId`, a later deploy fails because the slug is already taken; the error includes the app ID to save.
+
+A deployed app is served at `https://<organizationId>.sanity.run/applications/<appId>`.
+
+Agent terminals may disable interactive prompts even with a PTY (`TERM=dumb`). Use these flags rather than changing terminal settings or calling the applications API directly. Run `npm run deploy -- --help` to check which flags the installed CLI supports.
+
+This app is not a Studio. For a Studio's first hosted deployment, use `sanity deploy --url <hostname> --yes`; `studioHost`, if used in config, belongs at the top level, not inside `deployment`.
+
+## Working with the App SDK
+
+If the Sanity MCP server is available, call its `get_sanity_rules` tool with the `app-sdk` rule before writing SDK code. That rule is the maintained guide and supersedes the notes below.
+
+Essentials:
+
+- Data hooks suspend while loading. Wrap every data-fetching component in `<Suspense>`, keep one fetching hook per component, and always pass a `fallback` to `SanityApp`.
+- Fetch lists with `useDocuments` (or `usePaginatedDocuments`). They return document handles, not full documents. Spread a handle into `useDocumentProjection` to display fields, or into `useDocument` and `useEditDocument` for real-time editing.
+- Use `documentId` as the React key when rendering document lists, never the array index.
+- Do not hold document field values in `useState` and save on submit. Write through `useEditDocument` on change so content stays in sync with the Content Lake.
+- Prefer handles plus projections over raw GROQ. Reach for `useQuery` only when a complex query genuinely needs it.
+- Build UI with Sanity UI primitives like `Card`, `Stack`, `Flex`, `Text`, and `Button` for a look consistent with Sanity tooling.
+- Hooks that talk to the Dashboard itself are imported from `@sanity/sdk-react/dashboard`, not `@sanity/sdk-react`. Examples: `useNavigate`, `useOrganizationId`, `useApplications`, `useApplication`, `useWindowTitle`, `useNavigateToStudioDocument`.
+
+## Documentation
+
+- App SDK docs: https://www.sanity.io/docs/app-sdk
+- Best practices: https://www.sanity.io/docs/app-sdk/sdk-best-practices
+- Editing documents: https://www.sanity.io/docs/app-sdk/editing-documents
+- Configuration: https://www.sanity.io/docs/app-sdk/sdk-configuration
+- Sanity UI with the App SDK: https://www.sanity.io/docs/app-sdk/sanity-ui-sdk
+- Sanity UI docs: https://www.sanity.io/ui
+- API reference with current signatures: https://reference.sanity.io/_sanity/sdk-react/

package/templates/shared/dashboard/app-sanity-ui/README.md

@@ -0,0 +1,31 @@
+# Sanity App
+
+A custom application built with the [Sanity App SDK](https://www.sanity.io/docs/app-sdk?utm_source=readme) and [Sanity UI](https://www.sanity.io/ui?utm_source=readme). It is a React app that runs inside your organization's Sanity Dashboard, in development and when deployed.
+
+This app is set up for the Sanity Dashboard beta: `sanity.cli.ts` declares it with `defineApplication`.
+
+## Commands
+
+- `npm run dev` starts a local Sanity Dashboard (by default at http://localhost:3333, with the app on port 3334) and loads your app into it. Open it and sign in with your Sanity account.
+- `npm run build` builds the app for production.
+- `npm run deploy` deploys the app to your organization's Sanity Dashboard. The first deploy creates the app.
+
+## Configuration
+
+- `src/App.tsx` is the app entry point. The `SanityApp` config sets which project and dataset the app reads content from.
+- `sanity.cli.ts` declares the app with `defineApplication`:
+  - `title`: the app's name in the Dashboard.
+  - `slug`: the app's unique address in your organization, used to create the app on its first deploy. Lowercase letters, numbers and hyphens, starting with a letter.
+  - `organizationId`: the organization the app belongs to.
+  - `entry`: the app entry path.
+
+After the first deploy, add the app ID it prints to `sanity.cli.ts` as `deployment.appId` so later deploys update the same app.
+
+## Learn more
+
+- [App SDK Quickstart Guide](https://www.sanity.io/docs/app-sdk/sdk-quickstart?utm_source=readme)
+- [App SDK documentation](https://www.sanity.io/docs/app-sdk?utm_source=readme)
+- [Using Sanity UI with the App SDK](https://www.sanity.io/docs/app-sdk/sanity-ui-sdk?utm_source=readme)
+- [API reference](https://reference.sanity.io/_sanity/sdk-react/)
+- [Deploying your app](https://www.sanity.io/docs/app-sdk/sdk-deployment?utm_source=readme)
+- [SDK Explorer with example apps](https://sdk-explorer.sanity.io)

package/templates/shared/tsconfig.json

@@ -10,6 +10,7 @@
     "moduleDetection": "force",
     "isolatedModules": true,
     "jsx": "preserve",
+    "noUncheckedSideEffectImports": false,
     "incremental": true
   },
   "include": ["**/*.ts", "**/*.tsx"],