@sanity/asset-utils
Advanced tools
<!-- This file is AUTO-GENERATED, edit _README.template.md or tweak scripts/generateDocs.ts -->
@sanity/asset-utils is a utility library for working with Sanity assets. It provides functions to build URLs for images and files stored in Sanity's content lake, as well as to extract metadata and perform other common tasks related to asset management.
Building Image URLs
This feature allows you to build URLs for images stored in Sanity. You need to provide the project ID, dataset, and the source object containing the asset ID.
const { buildImageUrl } = require('@sanity/asset-utils');
const imageUrl = buildImageUrl({ projectId: 'yourProjectId', dataset: 'yourDataset', source: { assetId: 'image-abc123-200x200-png' } });
console.log(imageUrl);Extracting Metadata
This feature allows you to extract metadata from an asset ID. The metadata includes information such as the asset type, ID, extension, and dimensions.
const { getAsset } = require('@sanity/asset-utils');
const asset = getAsset('image-abc123-200x200-png');
console.log(asset);Building File URLs
This feature allows you to build URLs for files stored in Sanity. Similar to building image URLs, you need to provide the project ID, dataset, and the source object containing the asset ID.
const { buildFileUrl } = require('@sanity/asset-utils');
const fileUrl = buildFileUrl({ projectId: 'yourProjectId', dataset: 'yourDataset', source: { assetId: 'file-abc123-pdf' } });
console.log(fileUrl);Cloudinary is a cloud-based service that provides an end-to-end image and video management solution. It offers similar functionalities to @sanity/asset-utils, such as building URLs for images and files, but also includes advanced features like image transformations, video processing, and a comprehensive media library.
Imgix is a real-time image processing service that allows you to build URLs for images with various transformations applied. It is similar to @sanity/asset-utils in terms of URL building but offers more advanced image manipulation capabilities, such as cropping, resizing, and applying filters.
Sharp is a high-performance image processing library for Node.js. It allows you to perform various image transformations, such as resizing, cropping, and format conversion. While it does not provide URL building functionalities, it is a powerful tool for image manipulation, which can complement the features of @sanity/asset-utils.
Reusable utility functions for dealing with image and file assets in Sanity.
[!IMPORTANT] This package does not resolve any information from the Sanity APIs - it does no asynchronous operations and only has the information that you pass it. You cannot, for instance, get the LQIP, BlurHash, image palette and similar information without requesting it from the Sanity API.
$ npm install @sanity/asset-utils
// ESM / TypeScript
import {someUtilityFunction} from '@sanity/asset-utils'
// CommonJS
const {someUtilityFunction} = require('@sanity/asset-utils')
An HTML version is also available, which also includes interface definitions, constants and more.
▸ buildFilePath(asset: SanityFileUrlParts | FileUrlBuilderOptions, options?: PathBuilderOptions): string
Builds the base file path from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset | SanityFileUrlParts | FileUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
options | PathBuilderOptions | (Optional) Project ID and dataset the file belongs to, along with other options |
Returns: string
Defined in src/paths.ts:77
▸ buildFileUrl(asset: FileUrlBuilderOptions, options?: PathBuilderOptions): string
Builds the base file URL from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset | FileUrlBuilderOptions | An asset-like shape defining ID and extension |
options | PathBuilderOptions | (Optional) Project ID and dataset the file belongs to, along with other options |
Returns: string
Defined in src/paths.ts:102
▸ buildImagePath(asset: SanityImageUrlParts | ImageUrlBuilderOptions, options?: PathBuilderOptions): string
Builds the base image path from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset | SanityImageUrlParts | ImageUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
options | PathBuilderOptions | (Optional) Project ID and dataset the image belongs to, along with other options |
Returns: string
Defined in src/paths.ts:33
▸ buildImageUrl(asset: SanityImageUrlParts | ImageUrlBuilderOptions, options?: PathBuilderOptions): string
Builds the base image URL from the minimal set of parts required to assemble it
| Name | Type | Description |
|---|---|---|
asset | SanityImageUrlParts | ImageUrlBuilderOptions | An asset-like shape defining ID, dimensions and extension |
options | PathBuilderOptions | (Optional) Project ID and dataset the image belongs to |
Returns: string
Defined in src/paths.ts:61
▸ getAssetDocumentId(src: unknown): string
Tries to resolve the asset document ID from any inferrable structure
| Name | Type | Description |
|---|---|---|
src | unknown | Input source (image/file object, asset, reference, id, url, path) |
Returns: string
Defined in src/resolve.ts:331
▸ getAssetUrlType(url: string): "image" | "file" | false
Validates that a given URL is a Sanity asset URL, and returns the asset type if valid.
| Name | Type | Description |
|---|---|---|
url | string | URL to extract asset type from |
Returns: "image" | "file" | false
Defined in src/parse.ts:183
▸ getDefaultCrop(): SanityImageCrop
Returns cloned version of the default crop (prevents accidental mutations)
Returns: SanityImageCrop
Defined in src/hotspotCrop.ts:33
▸ getDefaultHotspot(): SanityImageHotspot
Returns cloned version of the default hotspot (prevents accidental mutations)
Returns: SanityImageHotspot
Defined in src/hotspotCrop.ts:41
▸ getExtension(src: SanityAssetSource): string
Returns the file extension for a given asset
| Name | Type | Description |
|---|---|---|
src | SanityAssetSource | Input source (file/image object, asset, reference, id, url, path) |
Returns: string
Defined in src/resolve.ts:93
▸ getFile(src: SanityFileSource, project?: SanityProjectDetails): ResolvedSanityFile
Tries to resolve an file object with as much information as possible, from any inferrable structure (id, url, path, file object etc)
| Name | Type | Description |
|---|---|---|
src | SanityFileSource | Input source (file object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the file belongs to |
Returns: ResolvedSanityFile
Defined in src/resolve.ts:233
▸ getFileAsset(src: SanityFileSource, options?: PathBuilderOptions): SanityFileAsset
Tries to resolve a (partial) file asset document with as much information as possible, from any inferrable structure (id, url, path, file object etc)
| Name | Type | Description |
|---|---|---|
src | SanityFileSource | Input source (file object, asset, reference, id, url, path) |
options | PathBuilderOptions | (Optional) Project ID and dataset the file belongs to, along with other options |
Returns: SanityFileAsset
Defined in src/resolve.ts:274
▸ getIdFromString(str: string): string
Tries to cooerce a string (ID, URL or path) to an image asset ID
| Name | Type | Description |
|---|---|---|
str | string | Input string (ID, URL or path) |
Returns: string
Defined in src/resolve.ts:380
▸ getImage(src: SanityImageSource, project?: SanityProjectDetails): ResolvedSanityImage
Tries to resolve an image object with as much information as possible, from any inferrable structure (id, url, path, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the image belongs to |
Returns: ResolvedSanityImage
Defined in src/resolve.ts:124
▸ getImageAsset(src: SanityImageSource, project?: SanityProjectDetails): SanityImageAsset
Tries to resolve a (partial) image asset document with as much information as possible, from any inferrable structure (id, url, path, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the image belongs to |
Returns: SanityImageAsset
Defined in src/resolve.ts:178
▸ getImageDimensions(src: SanityImageSource): SanityImageDimensions
Returns the width, height and aspect ratio of a passed image asset, from any inferrable structure (id, url, path, asset document, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
Returns: SanityImageDimensions
Defined in src/resolve.ts:63
▸ getProject(src: SanityImageSource): SanityProjectDetails
Resolves project ID and dataset the image belongs to, based on full URL or path
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Image URL or path |
Returns: SanityProjectDetails
Defined in src/resolve.ts:442
▸ getUrlFilename(url: string): string
Strips the CDN URL, path and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → filename-200x200.jpg
| Name | Type | Description |
|---|---|---|
url | string | URL to get filename from |
Returns: string
Defined in src/paths.ts:189
▸ getUrlPath(url: string): string
Strips the CDN URL and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → images/project/dataset/filename-200x200.jpg
| Name | Type | Description |
|---|---|---|
url | string | URL to get path name from |
Returns: string
Defined in src/paths.ts:159
▸ getVanityStub(originalFilename: string | undefined, vanityFilename: string | undefined, options?: PathBuilderOptions): string
Get the "path stub" at the end of the path, if the user hasn't explicitly opted out of this behavior
| Name | Type | Description |
|---|---|---|
originalFilename | string | undefined | The original filename of the asset |
vanityFilename | string | undefined | The vanity filename of the asset |
options | PathBuilderOptions | (Optional) Options to control the behavior of the path builder |
Returns: string
Defined in src/paths.ts:226
▸ isAssetFilename(filename: string): boolean
Returns whether or not the passed filename is a valid file or image asset filename
| Name | Type | Description |
|---|---|---|
filename | string | Filename to validate |
Returns: boolean
Defined in src/resolve.ts:492
▸ isAssetId(documentId: string): boolean
Checks whether or not the given document ID is a valid Sanity asset document ID (file or image)
| Name | Type | Description |
|---|---|---|
documentId | string | Document ID to check |
Returns: boolean
Defined in src/asserters.ts:121
▸ isAssetIdStub(stub: unknown): stub is SanityAssetIdStub
Checks whether or not the given source is an asset ID stub (an object containing an _id property)
| Name | Type | Description |
|---|---|---|
stub | unknown | Possible asset id stub |
Returns: stub is SanityAssetIdStub
Defined in src/asserters.ts:40
▸ isAssetObjectStub(stub: unknown): stub is SanityAssetObjectStub
Checks whether or not the given source is an asset object stub
| Name | Type | Description |
|---|---|---|
stub | unknown | Possible asset object stub |
Returns: stub is SanityAssetObjectStub
Defined in src/asserters.ts:132
▸ isAssetPathStub(stub: unknown): stub is SanityAssetPathStub
Checks whether or not the given source is an asset path stub (an object containing a path property)
| Name | Type | Description |
|---|---|---|
stub | unknown | Possible asset path stub |
Returns: stub is SanityAssetPathStub
Defined in src/asserters.ts:52
▸ isAssetUrlStub(stub: unknown): stub is SanityAssetUrlStub
Checks whether or not the given source is an asset URL stub (an object containing a url property)
| Name | Type | Description |
|---|---|---|
stub | unknown | Possible asset url stub |
Returns: stub is SanityAssetUrlStub
Defined in src/asserters.ts:64
▸ isDefaultCrop(crop: SanityImageCrop): boolean
Returns whether or not the passed crop has the default values for a crop region
| Name | Type | Description |
|---|---|---|
crop | SanityImageCrop | The crop to return whether or not is the default crop |
Returns: boolean
Defined in src/hotspotCrop.ts:50
▸ isDefaultHotspot(hotspot: SanityImageHotspot): boolean
Returns whether or not the passed hotspot has the default values for a hotspot region
| Name | Type | Description |
|---|---|---|
hotspot | SanityImageHotspot | The hotspot to return whether or not is the default hotspot |
Returns: boolean
Defined in src/hotspotCrop.ts:71
▸ isFileAssetFilename(filename: string): boolean
Returns whether or not the passed filename is a valid file asset filename
| Name | Type | Description |
|---|---|---|
filename | string | Filename to validate |
Returns: boolean
Defined in src/resolve.ts:481
▸ isFileAssetId(documentId: string): boolean
Checks whether or not the given document ID is a valid Sanity file asset document ID
| Name | Type | Description |
|---|---|---|
documentId | string | Document ID to check |
Returns: boolean
Defined in src/asserters.ts:110
▸ isFileSource(src: unknown): src is SanityFileSource
Return whether or not the passed source is a file source
| Name | Type | Description |
|---|---|---|
src | unknown | Source to check |
Returns: src is SanityFileSource
Defined in src/resolve.ts:503
▸ isImageAssetFilename(filename: string): boolean
Returns whether or not the passed filename is a valid image asset filename
| Name | Type | Description |
|---|---|---|
filename | string | Filename to validate |
Returns: boolean
Defined in src/resolve.ts:470
▸ isImageAssetId(documentId: string): boolean
Checks whether or not the given document ID is a valid Sanity image asset document ID
| Name | Type | Description |
|---|---|---|
documentId | string | Document ID to check |
Returns: boolean
Defined in src/asserters.ts:99
▸ isImageSource(src: unknown): src is SanityImageSource
Return whether or not the passed source is an image source
| Name | Type | Description |
|---|---|---|
src | unknown | Source to check |
Returns: src is SanityImageSource
Defined in src/resolve.ts:515
▸ isInProgressUpload(stub: unknown): stub is SanityFileUploadStub | SanityImageUploadStub
Checks whether or not the given source is an in-progress upload (has upload property but no asset property)
| Name | Type | Description |
|---|---|---|
stub | unknown | Possible in-progress upload |
Returns: stub is SanityFileUploadStub | SanityImageUploadStub
Defined in src/asserters.ts:145
▸ isReference(ref: unknown): ref is SanityReference
Checks whether or not the given source is a Sanity reference (an object containing _ref string key)
| Name | Type | Description |
|---|---|---|
ref | unknown | Possible reference |
Returns: ref is SanityReference
Defined in src/asserters.ts:28
▸ isSanityAssetUrl(url: string): boolean
Checks whether or not a given URL is a valid Sanity asset URL
| Name | Type | Description |
|---|---|---|
url | string | URL to test |
Returns: boolean
Defined in src/urls.ts:10
▸ isSanityFileAsset(src: unknown): src is SanityFileAsset
Checks whether or not the given source is a (partial) sanity file asset document. Only checks the _type property, all other properties may be missing
| Name | Type | Description |
|---|---|---|
src | unknown | Source to check |
Returns: src is SanityFileAsset
Defined in src/asserters.ts:76
▸ isSanityFileUrl(url: string): boolean
Checks whether or not a given URL is a valid Sanity file asset URL
| Name | Type | Description |
|---|---|---|
url | string | URL to test |
Returns: boolean
Defined in src/urls.ts:32
▸ isSanityImageAsset(src: unknown): src is SanityImageAsset
Checks whether or not the given source is a (partial) sanity image asset document. Only checks the _type property, all other properties may be missing
| Name | Type | Description |
|---|---|---|
src | unknown | Source to check |
Returns: src is SanityImageAsset
Defined in src/asserters.ts:88
▸ isSanityImageUrl(url: string): boolean
Checks whether or not a given URL is a valid Sanity image asset URL
| Name | Type | Description |
|---|---|---|
url | string | URL to test |
Returns: boolean
Defined in src/urls.ts:21
▸ isUnresolvableError(err: unknown): err is UnresolvableError
Checks whether or not an error instance is of type UnresolvableError
| Name | Type | Description |
|---|---|---|
err | unknown | Error to check for unresolvable error type |
Returns: err is UnresolvableError
Defined in src/errors.ts:29
▸ isValidFilename(filename: string): boolean
Checks whether or not a given filename matches the expected Sanity asset filename pattern
| Name | Type | Description |
|---|---|---|
filename | string | Filename to check for validity |
Returns: boolean
Defined in src/paths.ts:213
▸ parseAssetFilename(filename: string): SanityAssetIdParts
Parses a Sanity asset filename into individual parts (type, id, extension, width, height)
| Name | Type | Description |
|---|---|---|
filename | string | Filename to parse into named parts |
Returns: SanityAssetIdParts
Defined in src/parse.ts:94
▸ parseAssetId(documentId: string): SanityAssetIdParts
Parses a Sanity asset document ID into individual parts (type, id, extension, width/height etc)
| Name | Type | Description |
|---|---|---|
documentId | string | Document ID to parse into named parts |
Returns: SanityAssetIdParts
Defined in src/parse.ts:36
▸ parseAssetUrl(url: string): SanityAssetUrlParts
Parses a full Sanity asset URL into individual parts (type, project ID, dataset, id, extension, width, height)
| Name | Type | Description |
|---|---|---|
url | string | Full URL to parse into named parts |
Returns: SanityAssetUrlParts
Defined in src/parse.ts:118
▸ parseFileAssetId(documentId: string): SanityFileAssetIdParts
Parses a Sanity file asset document ID into individual parts (type, id, extension)
| Name | Type | Description |
|---|---|---|
documentId | string | File asset document ID to parse into named parts |
Returns: SanityFileAssetIdParts
Defined in src/parse.ts:56
▸ parseFileAssetUrl(url: string): SanityFileUrlParts
Parses a full Sanity file asset URL into individual parts (type, project ID, dataset, id, extension, width, height)
| Name | Type | Description |
|---|---|---|
url | string | Full URL to parse into named parts |
Returns: SanityFileUrlParts
Defined in src/parse.ts:167
▸ parseImageAssetId(documentId: string): SanityImageAssetIdParts
Parses a Sanity image asset document ID into individual parts (type, id, extension, width, height)
| Name | Type | Description |
|---|---|---|
documentId | string | Image asset document ID to parse into named parts |
Returns: SanityImageAssetIdParts
Defined in src/parse.ts:75
▸ parseImageAssetUrl(url: string): SanityImageUrlParts
Parses a full Sanity image asset URL into individual parts (type, project ID, dataset, id, extension, width, height)
| Name | Type | Description |
|---|---|---|
url | string | Full URL to parse into named parts |
Returns: SanityImageUrlParts
Defined in src/parse.ts:149
▸ tryGetAssetDocumentId(src: unknown): string | undefined
Tries to resolve the asset document ID from any inferrable structure
| Name | Type | Description |
|---|---|---|
src | unknown | Input source (image/file object, asset, reference, id, url, path) |
Returns: string | undefined
Defined in src/resolve.ts:367
▸ tryGetAssetPath(src: SanityAssetSource): string | undefined
Tries to get the asset path from a given asset source
| Name | Type | Description |
|---|---|---|
src | SanityAssetSource | The source image to infer an asset path from |
Returns: string | undefined
Defined in src/paths.ts:125
▸ tryGetExtension(src: SanityAssetSource): string | undefined
Returns the file extension for a given asset
| Name | Type | Description |
|---|---|---|
src | SanityAssetSource | Input source (file/image object, asset, reference, id, url, path) |
Returns: string | undefined
Defined in src/resolve.ts:110
▸ tryGetFile(src: SanityFileSource, project?: SanityProjectDetails): ResolvedSanityFile | undefined
Tries to resolve an file object with as much information as possible, from any inferrable structure (id, url, path, file object etc)
| Name | Type | Description |
|---|---|---|
src | SanityFileSource | Input source (file object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the file belongs to |
Returns: ResolvedSanityFile | undefined
Defined in src/resolve.ts:260
▸ tryGetFileAsset(src: SanityFileSource, options?: PathBuilderOptions): SanityFileAsset | undefined
Tries to resolve a (partial) file asset document with as much information as possible, from any inferrable structure (id, url, path, file object etc)
| Name | Type | Description |
|---|---|---|
src | SanityFileSource | Input source (file object, asset, reference, id, url, path) |
options | PathBuilderOptions | (Optional) Project ID and dataset the file belongs to, along with other options |
Returns: SanityFileAsset | undefined
Defined in src/resolve.ts:319
▸ tryGetIdFromString(str: string): string | undefined
Tries to cooerce a string (ID, URL or path) to an image asset ID
| Name | Type | Description |
|---|---|---|
str | string | Input string (ID, URL or path) |
Returns: string | undefined
Defined in src/resolve.ts:417
▸ tryGetImage(src: SanityImageSource, project?: SanityProjectDetails): ResolvedSanityImage | undefined
Tries to resolve an image object with as much information as possible, from any inferrable structure (id, url, path, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the image belongs to |
Returns: ResolvedSanityImage | undefined
Defined in src/resolve.ts:164
▸ tryGetImageAsset(src: SanityImageSource, project?: SanityProjectDetails): SanityImageAsset | undefined
Tries to resolve a (partial) image asset document with as much information as possible, from any inferrable structure (id, url, path, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
project | SanityProjectDetails | (Optional) Project ID and dataset the image belongs to |
Returns: SanityImageAsset | undefined
Defined in src/resolve.ts:219
▸ tryGetImageDimensions(src: SanityImageSource): SanityImageDimensions | undefined
Returns the width, height and aspect ratio of a passed image asset, from any inferrable structure (id, url, path, asset document, image object etc)
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Input source (image object, asset, reference, id, url, path) |
Returns: SanityImageDimensions | undefined
Defined in src/resolve.ts:81
▸ tryGetProject(src: SanityImageSource): SanityProjectDetails | undefined
Resolves project ID and dataset the image belongs to, based on full URL or path
| Name | Type | Description |
|---|---|---|
src | SanityImageSource | Image URL or path |
Returns: SanityProjectDetails | undefined
Defined in src/resolve.ts:461
▸ tryGetUrlFilename(url: string): string | undefined
Strips the CDN URL, path and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → filename-200x200.jpg
| Name | Type | Description |
|---|---|---|
url | string | URL to get filename from |
Returns: string | undefined
Defined in src/paths.ts:204
▸ tryGetUrlPath(url: string): string | undefined
Strips the CDN URL and query params from a URL, eg: https://cdn.sanity.io/images/project/dataset/filename-200x200.jpg?foo=bar → images/project/dataset/filename-200x200.jpg
| Name | Type | Description |
|---|---|---|
url | string | URL to get path name from |
Returns: string | undefined
Defined in src/paths.ts:177
MIT-licensed. See LICENSE.
FAQs
<!-- This file is AUTO-GENERATED, edit _README.template.md or tweak scripts/generateDocs.ts -->
The npm package @sanity/asset-utils receives a total of 207,957 weekly downloads. As such, @sanity/asset-utils popularity was classified as popular.
We found that @sanity/asset-utils demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 98 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh discusses the recent npm supply chain attacks on PodRocket, covering novel attack vectors and how developers can protect themselves.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.