Assets from
API to UI

If you have an existing Sanity project, you may prefer to read the documentation about asset handling for details on how to set it up in your application.

What's covered in this guide

You'll create a new free Sanity project using the Next.js template, publish new documents with Sanity Studio and explore how assets are uploaded, resized and embellished by AI Assist.

Create a new project

From the command line, create a new free Sanity project using the Next.js template.

If you don't already have an account with Sanity, you'll be prompted to create one.

npm create sanity@latest -- --template sanity-io/sanity-template-nextjs-clean --coupon=jpeg-guide

Now inside this directory, start the development server.

npm run dev

You should now have two apps running:

• http://localhost:3000 – Your Next.js app
• http://localhost:3333 – Your Sanity Studio

These apps are separately configured in the following directories:

├─ /nextjs-app
└─ /studio

The Sanity Studio is configured with code, edits you make to the configuration will render immediately in the development environment.

Content in Sanity Studio is written to a schemaless, cloud-hosted Dataset in what we call the Content Lake.

The Next.js app fetches content using Sanity Client with the GROQ query language.

Enter the Studio

Open http://localhost:3333 and log in to your Sanity Studio. The first tab that will open is the Presentation tool.

The Presentation tool is used to view your Next.js front end (http://localhost:3000) within an Iframe so that you can interact with your content.

💡 To see how Presentation can be used for interactive live preview of draft content, see the guide in this series on Visual Editing.

Publish a new post

Click "+ Create" from the top menu and select "Post."

The post document type currently has a few required fields. You will need to give this new document a:

• Title
• Slug
• Cover Image

  • and alternative text for the image

Once the Publish button is enabled, publish the post.

Open the post in Presentation

At the top of the document, you will see a box saying "Used on 2 pages" which you can open to show the locations of the current document in the front end.

Click the first location and you'll see the front end open side-by-side with the document editor. Make a change to the document and press Publish. You'll see the document update again, without a reload!

Crop and hotspot tool

The image rendered in the blog post is being cropped to a predetermined size and will be centered by default, but this may not be suitable for the image you uploaded.

Scroll to the Cover Image field in the document editor. You'll see the Crop icon in the top right hand corner. Click it, and you can now edit both the crop and focal area of the image.

Narrow the circle in the image to the part of the image you always want in view, and the crop area to the outer limits of what you would prefer to see.

You should see the front-end preview update as you make changes to the crop and focal areas. The image will still be the same pixel dimensions as before, but the region that is cropped is now effected by your choices in the Studio.

This feature allows editors to create curated images, without uploading multiple versions that are cropped with other tools, while your front-end renders consistent images on any page.

Automatic alt text with AI Assist

This template already has the AI Assist Studio plugin installed with some configuration settings. For this image field, the option to automatically generate alt text is available—however AI Assist is opt-in.

If you click the Assist icon above the Alternative text field, you should see an instruction Generate image description. Click this, and then click Enable AI Assist.

Click Generate image description again and you will see the assistant go to work, and briefly after write the alternative text directly to the field.

With AI Assist now activated—this is now automatic for future images! Try it by clearing the image field, uploading (or selecting) another image and the assistant will update the field value.

How this works

Sanity Studio schema types

Open studio/src/schemaTypes/documents/post.ts

Content types in Sanity Studio are made available by configuration files that are all registered to your sanity.config.ts file (explained below). This particular file registers the document type post and includes many fields, including this one named coverImage.

There are many field types available and every type has unique options. For this image field type the hotspot option is enabled.

The configuration of aiAssist is also found here, which enables the assistant to write an automatically generated description to the nominated field path.

Unsplash source and AI Assist plugins

Open studio/sanity.config.ts

All of your Sanity Studio's configuration can be found in sanity.config.ts, scroll down to the plugins section and you will see the unsplashImageAsset and assist plugins.

CoverImage component

Open nextjs-app/app/components/CoverImage.tsx

This component takes the value of the coverImage field—when queried by Sanity Client—and renders it into Next.js Image component.

This works because of the urlForImage function which takes the response from the Content Lake, and generates a unique URL to return the image at a specific size (1280x720) in the most efficient format possible for this browser.

To see what the original source data looks like, open the Vision tool in Sanity Studio and perform this query:

*[_type == "post"].coverImage

In the response you should see something like this, which contains the crop and hotspot dimensions, the alt text generated by AI Assist, and a "reference" to the image by its ID.

[
  {
    "hotspot": {
      "_type": "sanity.imageHotspot",
      "width": 0.3961148648648647,
      "x": 0.4247255067567567,
      "y": 0.34937890624999995,
      "height": 0.20537499999999997
    },
    "_type": "image",
    "alt": "a cake with pears and pomegranate seeds on top",
    "asset": {
      "_ref": "image-0ff15190924ae1d03758181418fc1225cc388fd2-5504x8256-jpg",
      "_type": "reference"
    },
    "crop": {
      "right": 0,
      "top": 0.21860156249999996,
      "left": 0,
      "bottom": 0.3235195312499999,
      "_type": "sanity.imageCrop"
    }
  }
]

This asset reference could be expanded to reveal even more metadata about the original image document—but its ID alone is enough to generate this URL thanks to the Sanity Image Builder library.

Next steps

Some ideas of what you might do next.

• Commit this repository to your Git provider and deploy to Vercel to share these live previews with content creators
• Add or edit Sanity Studio schema types. The template comes with a few already created, try adding a new field to post.ts in the /studio directory and see how the Studio updates imediately.
• Explore GROQ, queries.ts in the /nextjs-app directory contains all the queries that the Next.js app currently makes. You can test queries in the Studio using the Vision tool.
• Take the Day One with Sanity Studio Course to get a from-the-ground-up understanding of how to create new Sanity projects.