Configuration

Learn how to connect your custom app to your Sanity content

App SDK apps have two separate configuration files. The CLI configuration (sanity.cli.ts) controls your project setup, build tooling, and deployment. The runtime configuration (SanityConfig) connects your app to one or more Sanity projects at runtime.

The sanity.cli.ts file at the root of your project defines how the Sanity CLI builds, serves, and deploys your app. Pass your configuration to defineCliConfig:

import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  app: {
    organizationId: 'your-org-id',
    entry: './src/App.tsx',
  },
  deployment: {
    appId: 'your-app-id',
  },
})

You can customize how your app appears in the Sanity dashboard by setting an icon and a display title in the app object of your sanity.cli.ts file.

Use app.icon to provide a path to an SVG file, and app.title to set a default display name for your app.

import {defineCliConfig} from 'sanity/cli'

export default defineCliConfig({
  app: {
    organizationId: 'your-org-id',
    entry: './src/App.tsx',
    icon: './path/to/icon.svg',
    title: 'Default Title',
  },
  deployment: {
    appId: 'your-app-id',
  },
})

The runtime configuration connects your app to Sanity projects. Define one or more SanityConfig objects, each with a projectId and dataset, and pass them to the SanityApp provider component:

import {SanityApp, type SanityConfig} from '@sanity/sdk-react'

export function App() {
  const config: SanityConfig[] = [
    {
      projectId: 'your-project-id',
      dataset: 'your-dataset-name',
    }
  ]
  return (
    <div className="app-container">
      <SanityApp config={config} fallback={<div>Loading...</div>}>
        {/* add your own components here! */}
      </SanityApp>
    </div>
  )
}

export default App

• projectId: the Sanity project ID to connect to. Your app needs this value to fetch content.
• dataset: the dataset name to query. Your app needs this value to fetch content.
• studio: configuration for connecting to a specific Sanity Studio instance. Additional properties include auth for custom authentication.

The CLI configuration file supports the following properties:

• app.organizationId (required): the Sanity organization ID that owns this app.
• app.entry (optional): the file path to your app's entry point. Defaults to ./src/App.
• deployment.appId (optional): a unique identifier for your deployed app. Set automatically on first deploy.
• server.port and server.hostname (optional): local development server settings. Defaults to localhost:3333.

The SanityApp component wraps your application and provides all child components with the context needed to use SDK hooks and methods. It uses React Suspense internally. Props:

• config: an array of SanityConfig objects. Each needs a projectId and dataset. Required for standalone apps. Optional when running inside Sanity Studio (zero-config mode).
• fallback (optional): a React node to display while the SDK initializes.

Place SanityApp at the root of your component tree. All SDK hooks must be called from components rendered inside SanityApp.

Environment variables prefixed with SANITY_APP_ are automatically picked up by the Sanity CLI tool, development server, and bundler.

Any found environment variables are available as process.env.SANITY_APP_VARIABLE_NAME—even in browser code.

By requiring this SANITY_APP_ prefix, we prevent unrelated (and potentially sensitive) environment variables from getting exposed to the browser bundle. You can learn more about environment variables in the Studio documentation.

When you deploy your app for the first time with npx sanity deploy, the CLI prompts you for an app identifier. You can manage your deployed app's settings in Manage.

In your app directory, run the dev command:

npm run dev

pnpm run dev

yarn run dev

bun run dev

You should get a confirmation like the one displayed below.

Dev server started on port 3333
View your app in the Sanity dashboard here:
https://www.sanity.io/@[ORGANIZATION-ID]?dev=http%3A%2F%2Flocalhost%3A3333