# Course: Build content apps with Sanity App SDK https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk Building fast, real-time content authoring applications has never been simpler. Create a feedback processing application with user assignment, AI analysis and more. --- ## Navigation **Track:** [Mastering content operations](https://www.sanity.io/learn/track/sanity-developer-essentials) · [View as markdown](https://www.sanity.io/learn/track/sanity-developer-essentials.md) ## Contents 1. [Building content apps](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/building-content-apps) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/building-content-apps.md) 2. [Create a new Project and Studio](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/create-a-new-project-and-studio) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/create-a-new-project-and-studio.md) 3. [Quickstart a new App SDK app ](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/quickstart-a-new-app-sdk-app) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/quickstart-a-new-app-sdk-app.md) 4. [useDocuments](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-documents) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-documents.md) 5. [useDocumentProjection](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document-projection) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document-projection.md) 6. [useDocument](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document.md) 7. [useEditDocument](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-edit-document) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-edit-document.md) 8. [useApplyDocumentActions](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-apply-document-actions) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-apply-document-actions.md) 9. [useDocumentEvent](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document-event) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-document-event.md) 10. [useUsers](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-users) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-users.md) 11. [useUser](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-user) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-user.md) 12. [useNavigateToStudioDocument](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-navigate-to-studio-document) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-navigate-to-studio-document.md) 13. [useClient](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-client) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-client.md) 14. [Deployment and finishing touches](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/deployment-and-finishing-touches) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/deployment-and-finishing-touches.md) 15. [SDK Quiz](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/sdk-quiz) · [markdown](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/sdk-quiz.md) --- ## Lesson 1: Building content apps https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/building-content-apps A true content operating system provides more than one way to author content. Build powerful, fit-for-purpose applications faster than ever before. > [Video: Building content apps](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/building-content-apps) The Sanity App SDK is a collection of utilities for building content applications backed by the Content Lake. It is headless by design, so you can use whatever front-end framework you like. In the React package, almost all of its functionality is provided by React Hooks. It is the fastest way to rapidly build task-specific applications for authors and editor teams to perform content operations. ## Why build content apps? Sanity Studio is a powerful and nearly infinitely customizable admin panel for creating and editing content. However, given its flexibility, it can become so complex that it becomes difficult for authors with a specific task in mind, especially one that needs to be done repetitively, to perform it efficiently. So, while Sanity Studio may be the default experience for all of your content operations, the Sanity App SDK provides a way to build novel applications with a specific job in mind. > When all you have is a hammer, everything looks like a nail Sanity Studio is a hammer, but not all content operations are nails. Sanity App SDK is a scalpel. And this is a tortured metaphor. For example, imagine a content author at a media publication who needs to process feedback. They could click through a Studio to find what they need, or you could build an application to do what they need faster and better. And that's what you'll build in this course. ## Prerequisites This course expects that you have a reasonable understanding of the Command Line, PNPM, React, TypeScript, and Sanity. You will not need to be an expert in any of these, but this course is written with the expectation that this is not your first time encountering these words. If you would prefer to get a top-to-bottom look at how to work with *Sanity, the platform*, you may be better served by the Day One with Sanity course. > [!TIP] > Take [Day one content operations](https://www.sanity.io/learn/course/day-one-with-sanity-studio) ## What you'll build ![An application with a list of feedback items on the left and a document editor on the right.](https://cdn.sanity.io/images/3do82whm/next/40e32fb51ae5fa89b6ed1ad41a822947bd83e523-2240x1480.png) You'll be building a single-purpose application for processing feedback. You might imagine this feedback is received from a comments form or email account. Your content authors need a more efficient way to see which feedback: - is pending approval to proceed in the workflow - should be marked as spam and dismissed - should be deleted - and to mark the sentiment of any feedback as positive, neutral or negative. Let's begin in the next lesson by first creating a new Sanity project and Studio. --- ## Lesson 2: Create a new Project and Studio https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/create-a-new-project-and-studio Get setup with a fresh hosted backend for your content, and the traditional administration panel for Sanity. > [Video: Create a new Project and Studio](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/create-a-new-project-and-studio) Content written to Sanity is stored within the Content Lake, not in Sanity Studio. The schema types you configure are made available in Sanity Studio, and it writes content of that shape to the Content Lake. You can think of the Sanity Studio as a *"window into the Content Lake."* ## So I don't need a Studio to build an SDK App? Nope! You can write data of any shape (that conforms to JSON) to the Content Lake. But having a Studio makes it easier to reason about our *complete* universe of content if we have one configured. It's also where you'd configure TypeScript types. So you'll start this course by creating a new Sanity project and Sanity Studio—you just won't need to edit any content there. ## Create a new project You can create a new free project and initialize a new Sanity Studio from one command using the Sanity CLI. If you do not yet have a Sanity account, you can create one during this process. You may like to create a parent folder to contain the projects you work on in this course, as your Sanity Studio and App SDK app will live side-by-side. Once you have a Studio and App setup, your folder structure should look like this: ```text feedback-course ├── studio └── app-feedback ``` - [ ] **Run** the following command in your terminal to create a new Sanity project and Sanity Studio. ```sh:Terminal pnpm dlx create-sanity@latest --template blog --create-project "Feedback Processor" --dataset production --typescript --output-path studio ``` - [ ] **Run** the following from inside of the `/studio` directory ```sh:Terminal pnpm run dev ``` Open [http://localhost:3333](http://localhost:3333) in your browser and log in. You should now see the Sanity Studio dashboard interface with Post, Category and Author schema types already configured. ## Add "Feedback" schema types The schema types that appear in the Structure tool of Sanity Studio are defined in the project's configuration files. You'll need to create a new file to add "Feedback" type documents as an option in the Studio and a TypeScript type for your App. - [ ] **Create** a new file for Feedback type documents ```typescript:studio/schemaTypes/feedbackType.ts import {defineField, defineType} from 'sanity' export const feedbackType = defineType({ name: 'feedback', title: 'Feedback', type: 'document', fields: [ defineField({ name: 'content', type: 'text', }), defineField({ name: 'author', type: 'string', }), defineField({ name: 'email', type: 'string', }), defineField({ name: 'sentiment', type: 'string', options: {list: ['positive', 'neutral', 'negative'], layout: 'radio'}, }), defineField({ name: 'status', type: 'string', options: {list: ['pending', 'approved', 'spam'], layout: 'radio'}, }), defineField({ name: 'assignee', type: 'string', }), defineField({ name: 'notes', type: 'text', }), ], preview: { select: { title: 'content', subtitle: 'author', }, }, }) ``` **Update** the schema types index file to include the feedback schema type. ```typescript:studio/schemaTypes/index.ts import blockContent from './blockContent' import category from './category' import post from './post' import author from './author' import {feedbackType} from './feedbackType' export const schemaTypes = [post, author, category, blockContent, feedbackType] ``` You should now see an option in your Structure tool to list and create Feedback type documents. ## Import seed data It is easier to build front ends when you have content, and so some has been prepared for you already. - [ ] **Download** `feedback-seed.ndjson` - [ ] **Run** the following from the terminal, inside the `studio` folder to import 20 example Feedback type documents. ```sh:Terminal pnpm dlx sanity dataset import feedback-seed.ndjson production ``` Open your Studio to confirm these documents are now visible, there's a mix of spam comments and none of them have been marked to indicate their "sentiment," that's the job of our new app! Let's start building it next. --- ## Lesson 3: Quickstart a new App SDK app https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/quickstart-a-new-app-sdk-app Start a new App SDK app in seconds from the command line using the Sanity UI template. > [Video: Quickstart a new App SDK app ](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/quickstart-a-new-app-sdk-app) You've now got content to work with and a Sanity Studio, it's time to start building your app. - [ ] **Run** the following from the terminal in the root directory (above the `studio` directory) ```sh:Terminal # in the parent directory pnpm dlx sanity@latest init --template app-sanity-ui --typescript --output-path app-feedback ``` You may be prompted to select an Organization, select your personal organization, as that's where the project you created in the previous lesson was created. You should now have these two adjacent folders. ``` feedback-course ├── app-feedback └── studio ``` ## Why Sanity UI? The command you just ran uses the Sanity UI app template. This includes the required context and packages for the same front end library used in other Sanity applications like Sanity Studio, Media Library and Dashboard. You're free to use the front-end library of your choice in Sanity App SDK applications. For this course, however, you'll use Sanity UI so that the application you build shares visual harmony with the rest of the dashboard experience. > [!TIP] > [Sanity UI](https://www.sanity.io/ui) has its own documentation site with implementation details > [!TIP] > See the [App SDK docs](https://www.sanity.io/learn/docs/app-sdk/sanity-ui-sdk) for examples on how to install other styling libraries ## Running two apps By default, SDK Apps use the same port number (`3333`) as the Studio. To run the Studio and your applications simultaneously, you can update `sanity.cli.ts` of either one. Let's change the default port of the Studio. - [ ] **Update** the Sanity CLI config of the Sanity Studio ```typescript:studio/sanity.cli.ts import {defineCliConfig} from 'sanity/cli' export default defineCliConfig({ server: { port: 3334, }, // ...all other settings }) ``` Restart your Studio's development server, you'll get a new development URL. Open the Studio in your browser and be asked to create a new CORS origin. You can follow the instructions in the browser, or create a new origin using Sanity CLI with the following command run from inside your `studio` folder. ```sh:Terminal # in /studio pnpm dlx sanity@latest cors add http://localhost:3334 --allow ``` - [ ] **Run** the following inside the `app-feedback` folder to start the app's development server. ```sh # in /app-feedback pnpm run dev ``` > [!WARNING] > If you get an error about a mismatched Organization ID, you may have selected a different Organization to the one in which the project was created. Update `app-feedback/sanity.cli.ts` to use the correct Organization ID. You'll see a URL in the terminal to open the App running from within the Sanity Dashboard. Dashboard is the default "home screen" where authors can move between deployed Studios and other applications—such as the one you're building right now. The Dashboard also provides authentication to your app. In a large enough organization, you may have many teams of authors working between or across multiple projects all served by deployed Sanity Studio instances or Apps of all shapes and sizes. Content operations are not the job of a one-size-fits-nobody CMS! ## Targeting your project(s) While this app will only target one project, an App SDK app can target multiple (worth knowing: Sanity Studio can't do this). The entry point for your application is `App.tsx`, you can see this defined in `sanity.cli.ts`. - [ ] **Update** the main `App.tsx` file with the details found in your `studio/sanity.config.ts` file. ```typescript:app-feedback/src/App.tsx const sanityConfigs: SanityConfig[] = [ { projectId: 'REPLACE-WITH-YOUR-PROJECT-ID', dataset: 'production', }, ] ``` There is an `ExampleComponent` already loaded as the main child of the application. Let's replace this with our first use of the App SDK's React hooks to query for a list of documents. --- ## Lesson 4: useDocuments https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-documents Performant querying for a live-updating list of documents has never been simpler. > [Video: useDocuments](https://www.sanity.io/learn/course/build-content-apps-with-sanity-app-sdk/use-documents) Maybe the most basic thing we can do when creating an application is query and render a list of documents. In this lesson, you'll do it using the `useDocuments` hook. Before we do, let's interrogate this decision. ## Why not use client.fetch? [Sanity Client](https://github.com/sanity-io/client) is the primary way JavaScript applications are built to interact with Sanity's APIs. The App SDK is a wrapper of Sanity Client for building apps and solves much of the UI complexity that comes with working with a lower-level client. For example, when you query documents with `client.fetch`, the list of documents will not update in real-time as documents change. You might also unknowingly fetch 10,000 documents. Edits made to these documents will not automatically create per-render optimistic updates in the UI. All complexity and performance concerns are bundled up in the App SDK's React hooks, making it simpler and faster for us to build better content applications. ## Why not useQuery? The App SDK provides the useQuery hook, which takes a GROQ query. We could use this hook for all our data fetching. However, many other hooks in the App SDK for React require "document handles" to be passed in as parameters. These can be created ad hoc from values in a document. Still, it's simpler to retrieve document handles in a parent component and pass them down to child components, which perform fetches or actions using those handles. ### When you might want useQuery There are some patterns where it makes more sense to use `useQuery` instead of `useDocuments`, such as when a parent component needs to know specific values of each document. For example, a component may need to know which day an event is on to render it into a calendar or the geolocation of an event to plot it on a map. In these instances, you may be better off fetching with `useQuery` documents and their values in the parent component. Just be aware that this can lead to overfetching. ## What are document handles? A [document handle](https://www.sanity.io/learn/docs/app-sdk/document-handles) contains at least two and up to four useful pieces of information about a document to identify its type and origin. By keeping the data returned by fetches of documents smaller, we maintain focus on improved performance in our applications. ```json { "dataset": "production", "documentId": "116d2c7a-d1de-4d00-9a88-8ac65ceaad10", "documentType": "feedback", "projectId": "xe385msc" } ``` ## tl;dr it's about more, smaller fetches In Server-Side Rendered (SSR) web application frontends, you have likely formed a habit of fetching **everything** your web page needed in one huge GROQ query using `client.fetch`. This isn't necessary in a Single Page Application (SPA). The happy path for App SDK apps is to filter for specific documents using `useDocuments` and pass down the returned document handles to components which individually fetch, edit and take actions on documents. Any concerns about caching, real-time and optimistic updates are all taken care of by the App SDK. ## Let's finally fetch something - [ ] **Create** a new component called `Feedback`, which will be the parent component of all our UI. ```tsx:app-feedback/src/Feedback.tsx import { Suspense, useState } from "react" import { DocumentHandle } from "@sanity/sdk-react" import { Card, Flex, Grid, Spinner } from "@sanity/ui" import { styled } from "styled-components" import { FeedbackList } from "./FeedbackList" const ScreenHeightCard = styled(Card)` height: 100vh; overflow: scroll; ` export function Feedback() { const [selectedFeedback, setSelectedFeedback] = useState(null) return ( }> {/* TODO: Add form */} ) } function Loading() { return ( ) } ``` > [!NOTE] > Don't forget your `Suspense` boundaries. The App SDK React Hooks use Suspense for data fetching. This means any component which uses one of these hooks could cause a re-render further up the component tree. Since this `Feedback` component will be rendering both the `FeedbackList` and `FeedbackEdit` form components, without being wrapped in `Suspense` an update in one component would force both to re-render. > [!TIP] > **Read more** about [`Suspense` in the React documentation](https://react.dev/reference/react/Suspense) - [ ] **Create** another component to query for the feedback documents. ```tsx:app-feedback/src/FeedbackList.tsx import { type DocumentHandle, useDocuments } from "@sanity/sdk-react" import { Stack, Button } from "@sanity/ui" type FeedbackListProps = { selectedFeedback: DocumentHandle | null setSelectedFeedback: (feedback: DocumentHandle | null) => void } export function FeedbackList({ selectedFeedback, setSelectedFeedback, }: FeedbackListProps) { const { data, hasMore, loadMore } = useDocuments({ documentType: "feedback", }) return ( {data?.map((feedback) => ( 
{JSON.stringify(feedback, null, 2)}
))} {hasMore && ) })} {hasMore &&