Using @sanity/image-url without a framework or build process

14 replies

Last updated: Mar 7, 2023

if I am not using a framework & don’t have any

build

process, can I still use @sanity/image-url ? How do I use it? The instructions say to “pass it your configured sanityClient” but I don’t know how/where that’s supposed to happen? Sorry for the basic question

AI Update

I can see why you're confused - the documentation examples assume you're using a module system with a configured Sanity client, which isn't straightforward without a build process. Let me clarify what's actually possible.

Based on the official documentation, @sanity/image-url is distributed as an NPM package designed to work in a module environment. The examples show importing it and passing a configured @sanity/client instance.

The honest answer: The @sanity/image-url library isn't officially documented for direct browser usage without a build process. The docs only cover NPM/module imports.

Your best option: Build URLs manually

The good news is you don't actually need the library! You can construct Sanity's image CDN URLs directly, which works perfectly without any build process or dependencies.

Here's how the URL structure works, based on the Image Pipeline documentation:

<!DOCTYPE html>
<html>
<head>
  <title>Sanity Images Example</title>
</head>
<body>
  <img id="myImage" alt="Example">
  
  <script>
    // Your project details
    const projectId = 'your-project-id'  // Get this from sanity.io/manage
    const dataset = 'production'          // Usually 'production'
    
    // Your image reference (from your Sanity query)
    // Format: image-{assetId}-{width}x{height}-{format}
    const imageRef = 'image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg'
    
    // Build the base URL
    const baseUrl = `https://cdn.sanity.io/images/${projectId}/${dataset}/${imageRef}`
    
    // Add transformations as query parameters
    const transformedUrl = `${baseUrl}?w=600&h=400&fit=crop&auto=format`
    
    // Use it!
    document.getElementById('myImage').src = transformedUrl
  </script>
</body>
</html>

Available URL parameters

You can add these as query parameters to transform your images (from the image transformations docs):

w=400 - Set width to 400px
h=300 - Set height to 300px
fit=crop - Crop to exact dimensions (also: max, fill, clip)
auto=format - Automatically serve WebP/AVIF to supported browsers
q=75 - Set quality (0-100)
blur=50 - Blur the image
rect=x,y,width,height - Crop to a specific rectangle

Example with multiple transformations:

const url = `https://cdn.sanity.io/images/${projectId}/${dataset}/${imageRef}?w=800&h=600&fit=max&auto=format&q=85`

Getting the image reference from Sanity

When you query Sanity, you'll get an image reference that looks like this:

// Example image object from a GROQ query
{
  "_type": "image",
  "asset": {
    "_ref": "image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg",
    "_type": "reference"
  }
}

Use that _ref value as your imageRef in the URL construction above.

About "passing a configured sanityClient"

The documentation mentions this because the library can accept a full client object, but when building URLs manually (as shown above), you only need your projectId and dataset - no client library required!

This manual approach is actually documented in the official Image Pipeline guide and works perfectly without any build tooling or JavaScript libraries.

How are you building your frontend?

Vanilla html/css/js

You’ll use the JS client you linked to create a configured client. You’ll need to use a bundler like Browserify or Webpack to be able to use modules, though. If you don’t want to do that, you won’t be able to use the url builder and you’ll have to use the HTTP API to get content from Sanity.

Yeah, I guess that's what I've been doing this whole time...I just don't know the nomenclature.

https://sanity-io-land.slack.com/archives/C011CAT70DD/p1677821863024369?thread_ts=1677821863.024369&cid=C011CAT70DD

The plugin was recommended to me, could you look at the thread and suggest another route?

Yeah, you can instead expand the reference in your query and get the url of the image in the CDN.

*[_type == 'collection' && title == "${collectionName}"] {
  'products': products[].product->,  
  'sets': sets[].set->{
   ...,
   'imageUrl': image.asset->.url
  }
}

you are so wonderful

You can then concatenate these params onto that url to present the image at the size/resolution/etc. you want.

Aw, thank you! Happy to help!

you made my monday better

💜

You saying that has made my monday better!

My coworker pointed out this morning that you actually can use those packages without a bundler because the most recent release of the client added Browser ESM CDN support . I’m afraid I can’t be much more helpful than that since I haven’t given it a go yet!

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for free Explore the demo