feat: add asset management functions and hooks #656

ryanbonial · 2025-10-30T03:06:30Z

Description

Added asset management capabilities to the SDK, including new hooks and utilities for working with assets. This PR introduces:

Core asset management functions in @sanity/sdk
React hooks in @sanity/sdk-react for asset operations
A new Assets demo route in the kitchensink app

The implementation provides a complete asset management solution with support for:

Querying assets with flexible filtering options
Uploading images and files
Deleting assets
Linking Media Library assets

What to review

Core asset functions in packages/core/src/assets/assets.ts
React hooks in packages/react/src/hooks/assets/
The demo implementation in apps/kitchensink-react/src/routes/AssetsRoute.tsx
Public API exports in both packages

Testing

The implementation includes:

Type safety with proper overloads for different asset kinds
Comprehensive error handling
A fully functional demo route that exercises all the new capabilities

Fun gif

vercel · 2025-10-30T03:06:35Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
sdk-docs	Ready	Preview, Comment	Jan 14, 2026 8:22pm
sdk-kitchensink-react	Ready	Preview, Comment	Jan 14, 2026 8:22pm

cngonzalez

I like having all these helper hooks! I'm not sure I fully understand why there's a need for a separate store, though. Can we treat image assets like documents?

Also added some comments on maybe using our existing tooling to keep this simple.

packages/core/src/assets/assets.ts

socket-security · 2025-10-30T22:28:42Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/@sanity/image-url@1.2.0

View full report

cngonzalez

A few nits but a larger comment:

I really like the addition of the utility hooks but I'm a bit confused about the implementation of useAssets and the underlying getAssetsState et al. I've got two main questions:

We're using the StateSource type but are we actually using a state at any point? (Or the associated subscription / unsubsciption logic). I couldn't see it, but I could be wrong. Should we, to be consistent?
useAssets diverges a bit from the rest of our codebase; I think it's returning whole documents. Should it conform more closely to useDocuments and return handles (we might even be able to pass the buck to getDocumentsState and have simpler logic)? And then we can implement a useAsset that returns the full document that can then be a full doc? Or is that annoying in practice?

cngonzalez · 2025-10-31T15:27:53Z

apps/kitchensink-react/src/routes/AssetsRoute.tsx

+  // Bump this to force a re-fetch of assets
+  const [refresh, setRefresh] = useState(0)
+  const [isUploading, setIsUploading] = useState(false)
+  const requeryTimeoutsRef = useRef<number[]>([])


Curious if we still need this after the move to queryStore? Or if this is logic we could already bake in to our assets store? My personal preference is that our usage of hooks in Kitchensink is pretty "vanilla" (mostly for e2e tests to be accurate)

cngonzalez · 2025-10-31T15:31:23Z

packages/core/src/_exports/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable simple-import-sort/exports */


Why disable here?

oops, good catch

should we remove this? i think we want this rule in this file especially

cngonzalez · 2025-10-31T18:18:50Z

packages/core/src/assets/assets.ts

+ * Runtime validator and type guard for image asset IDs
+ * @public
+ */
+export function isImageAssetId(value: string): value is ImageAssetId {


Should we use asset-utils for this as well? https://github.com/sanity-io/asset-utils/blob/bb980f9cdb10922e7c5a13eacab564581c6120d6/src/asserters.ts#L99

I think that importing from the monorepo would cause a dependency loop, so I'm hesitant to add it here.

Which monorepo do you mean?

I don't know if we got an answer to this conversation about importing from asset-utils to keep consistent with the rest of the org.

cngonzalez · 2025-11-04T13:27:25Z

packages/core/src/config/sanityConfig.ts

+/**
+ * Identifies a specific asset within a Sanity project/dataset.
+ * Includes optional `projectId`/`dataset` and the required `assetId` (asset document `_id`).
+ * Useful for cross-instance asset operations without relying on the active ResourceProvider.


I don't think I fully understand this comment -- what is meant by cross-instance? I'm also a little wary of the mental model of "this is a document but the _id has a different parameter name"

Cross-instance is across projects and datasets. This change is from Cole's suggestion here: https://sanity-io.slack.com/archives/C07RS3HV1K9/p1761929608902129?thread_ts=1761841748.625049&cid=C07RS3HV1K9

I like the addition of it. It makes it much easier to use assets from difference resources pretty easily.

I thought we are using the active resource provider -- the queryStore is tied to it (that could be my fault -- I pushed you in that direction). I'm just confused on how this behavior differs from other hooks, which I think will also allow a projectId/dataset param to find the right instance.

ryanbonial · 2025-11-04T22:32:20Z

@cngonzalez

The stateSource is being used for subscribing and unsubscribing using createStateSourceHook in the hook here, so it isn't easy to see explicitly because of the abstraction/generalization layer.
IMO the full asset document that is currently returned is a handle for the actual asset data that lives on the CDN. I'm concerned that adding an assetHandle that is only part of an asset document would be 2 layers of "handles"

cngonzalez · 2025-11-05T15:13:07Z

The stateSource is being used for subscribing and unsubscribing using createStateSourceHook in the hook here, so it isn't easy to see explicitly because of the abstraction/generalization layer.

I was multitasking and didn't write carefully 🤦 What I meant was, we're not using the Zustand store state as we do with other utilities. Stores like the documentStore and projectionStore use the bindActionByDataset utility to handle subscription logic and prevent over-fetching.

I actually don't think that assets should have a store or a state; to me, they're just documents. Which brings me to this:

IMO the full asset document that is currently returned is a handle for the actual asset data that lives on the CDN. I'm concerned that adding an assetHandle that is only part of an asset document would be 2 layers of "handles"

I'm mostly wary of having diverging implementations for things that are just documents. The sanity.imageAsset document behaves like a document, is indexed and queried as such, and belong to datasets. It has a pointer to CDN data but also has a ton of metadata, which makes them not small documents -- ref this https://ppsg7ml5.api.sanity.io/v2025-11-05/data/query/test?query=*%5B_type+%3D%3D+%27sanity.imageAsset%27%5D%5B0%5D&perspective=drafts

I would love if we could scale all the efficiencies we worked for (regarding document querying) to the way we work with assets, and I think the easiest way is if we treat the sanity.imageAsset documents as documents.

To be clear, I'm very much in favor of useDeleteAsset, useLinkMediaLibraryAsset, and useUploadAsset; I'm just imagining a world where they take in document handles, do a check to ensure that they're assets, and go about their business.

…perations

ryanbonial · 2025-11-24T19:52:26Z

@cngonzalez I think I have refactored to your suggestions. Please let me know if this is what you had in mind. Thanks

cngonzalez

Let me know if you want to chat or if I'm misunderstanding things! Sorry to drag this out.

cngonzalez · 2026-01-14T20:58:53Z

packages/core/src/_exports/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable simple-import-sort/exports */


should we remove this? i think we want this rule in this file especially

cngonzalez · 2026-01-14T20:59:22Z

packages/core/src/assets/assets.ts

+ * Runtime validator and type guard for image asset IDs
+ * @public
+ */
+export function isImageAssetId(value: string): value is ImageAssetId {


I don't know if we got an answer to this conversation about importing from asset-utils to keep consistent with the rest of the org.

cngonzalez · 2026-01-14T22:02:53Z

packages/core/src/assets/assets.ts

+ * Options for querying assets
+ * @public
+ */
+export interface AssetQueryOptions<


I'm sorry -- it's been a while and I didn't realize you'd made changes based on my feedback. I still feel pretty strongly that assets are just documents and we should maybe update / share useDocuments rather than having the complexity of a dedicated assets store. I think it also might simplify usage -- I notice a lot of re-querying and other things in the Kitchensink example that don't feel very SDK (or maybe those things don't need to be there and I'm misunderstanding?)

It would also mean that our signatures for useAssets and useDocuments could easily be the same. If we could abstract out the "meat" of useDocuments, so that useAssets could return the full AssetDocumentBase, while useDocuments returns DocumentHandles, I think we'd have a lot of the same functionality and optimization and upkeep would be a lot easier.

I apologize, I thought we'd discussed this but maybe it was all in my head.

cngonzalez · 2026-01-14T22:04:08Z

packages/core/CHANGELOG.md

@@ -2,29 +2,26 @@



We might want to not make changes to the changelog in this PR

cngonzalez · 2026-01-14T22:05:31Z

packages/core/src/assets/assets.ts

+  TProjectId extends string = string,
+> extends DatasetHandle<TDataset, TProjectId> {
+  assetId: string
+  mediaLibraryId: string


Should we mark this beta? I'm a bit wary of exposing something that uses the mediaLibraryId explicitly as public, especially with upcoming sources work

feat: add asset management functions and hooks

448a41b

vercel bot had a problem deploying to Preview – sdk-docs October 30, 2025 03:06 Failure

vercel bot had a problem deploying to Preview – sdk-kitchensink-react October 30, 2025 03:06 Failure

chore: fix exports

bcff699

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 03:20 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 03:20 View deployment

chore: fix export

2b1a5e7

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 14:42 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 14:42 View deployment

chore: add tests

3ac7342

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 15:55 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 15:55 View deployment

chore: style asset example

105ba04

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 16:24 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 16:24 View deployment

ryanbonial marked this pull request as ready for review October 30, 2025 16:25

ryanbonial requested a review from a team as a code owner October 30, 2025 16:25

ryanbonial requested review from binoy14 and cngonzalez and removed request for binoy14 October 30, 2025 16:25

chore: fix upload example

a94f8e7

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 16:29 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 16:29 View deployment

cngonzalez requested changes Oct 30, 2025

View reviewed changes

packages/core/src/assets/assets.ts Outdated Show resolved Hide resolved

packages/core/src/assets/assets.ts Outdated Show resolved Hide resolved

chore: refactor to use the existing queryStore

48a5540

vercel bot deployed to Preview – sdk-kitchensink-react October 30, 2025 21:34 View deployment

vercel bot deployed to Preview – sdk-docs October 30, 2025 21:35 View deployment

refactor: use @sanity/image-url instead of building a URL function

4d635e3

vercel bot deployed to Preview – sdk-kitchensink-react November 3, 2025 21:17 View deployment

vercel bot deployed to Preview – sdk-docs November 3, 2025 21:17 View deployment

cngonzalez reviewed Nov 4, 2025

View reviewed changes

Merge branch 'main' into rb/add-assets

cfbcfab

vercel bot deployed to Preview – sdk-kitchensink-react November 24, 2025 16:30 View deployment

vercel bot deployed to Preview – sdk-docs November 24, 2025 16:30 View deployment

refactor(assets): replace AssetHandle with DocumentHandle for asset o…

f0cbb2e

…perations

vercel bot deployed to Preview – sdk-kitchensink-react November 24, 2025 19:34 View deployment

vercel bot deployed to Preview – sdk-docs November 24, 2025 19:35 View deployment

Merge branch 'main' into rb/add-assets

75c627c

ryanbonial requested review from cngonzalez and colepeters November 24, 2025 19:51

vercel bot deployed to Preview – sdk-kitchensink-react November 24, 2025 19:52 View deployment

vercel bot deployed to Preview – sdk-docs November 24, 2025 19:52 View deployment

Merge branch 'main' into rb/add-assets

1168883

vercel bot deployed to Preview – sdk-kitchensink-react December 16, 2025 16:47 View deployment

vercel bot deployed to Preview – sdk-docs December 16, 2025 16:48 View deployment

Merge branch 'main' into rb/add-assets

c6c77da

vercel bot deployed to Preview – sdk-kitchensink-react December 30, 2025 22:24 View deployment

vercel bot deployed to Preview – sdk-docs December 30, 2025 22:25 View deployment

refactor: update useDeleteAsset tests to use DocumentHandle structure

df72ef3

vercel bot deployed to Preview – sdk-kitchensink-react December 30, 2025 22:52 View deployment

vercel bot deployed to Preview – sdk-docs December 30, 2025 22:52 View deployment

Merge branch 'main' into rb/add-assets

22b7ec0

vercel bot deployed to Preview – sdk-kitchensink-react January 14, 2026 20:22 View deployment

vercel bot deployed to Preview – sdk-docs January 14, 2026 20:22 View deployment

cngonzalez requested changes Jan 14, 2026

View reviewed changes

		@@ -1,3 +1,4 @@
		/* eslint-disable simple-import-sort/exports */

feat: add asset management functions and hooks #656

Are you sure you want to change the base?

feat: add asset management functions and hooks #656

Uh oh!

Conversation

ryanbonial commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What to review

Testing

Fun gif

Uh oh!

vercel bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cngonzalez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

socket-security bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cngonzalez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ryanbonial commented Nov 4, 2025

Uh oh!

cngonzalez commented Nov 5, 2025

Uh oh!

ryanbonial commented Nov 24, 2025

Uh oh!

cngonzalez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ryanbonial commented Oct 30, 2025 •

edited

Loading

vercel bot commented Oct 30, 2025 •

edited

Loading

socket-security bot commented Oct 30, 2025 •

edited

Loading