How to preserve image filenames in Sanity CDN URLs for SEO?

Great question! You're on the right track with originalFilename – this is exactly what you need for creating SEO-friendly image URLs.

Sanity supports what they call "vanity filenames" which lets you append a human-readable filename to the end of the hashed image URL. This gives you the SEO benefits you're looking for without changing how the CDN fundamentally works.

How Vanity Filenames Work

The CDN URL format is:

https://cdn.sanity.io/images/<projectId>/<dataset>/<hashedFileName>/<vanityFilename>?<params>

So instead of:

https://cdn.sanity.io/images/1234567/production/754c8d64997b668642bd2500f833722c6293cf8b-1766x1065.png?q=75&fit=clip&auto=format

You can have:

https://cdn.sanity.io/images/1234567/production/754c8d64997b668642bd2500f833722c6293cf8b-1766x1065.png/my-product-image.png?q=75&fit=clip&auto=format

The hash stays in the URL (it's required for the CDN's content-addressable architecture), but you get the human-readable filename at the end, which is what search engines care about.

Implementation with Gatsby

For Gatsby specifically, you'll need to:

1. Query the originalFilename field from your image assets in your GraphQL queries:

query {
  allSanityYourType {
    nodes {
      image {
        asset {
          url
          originalFilename
          # other fields you need
        }
      }
    }
  }
}

2. Append the filename when building your image URLs. If you're using gatsby-plugin-image or @sanity/image-url, you'll need to manually append /${originalFilename} to the generated URL.

Here's a practical example:

import imageUrlBuilder from '@sanity/image-url'

const builder = imageUrlBuilder(sanityConfig)

function urlFor(source, originalFilename) {
  const baseUrl = builder.image(source).url()
  return originalFilename ? `${baseUrl}/${originalFilename}` : baseUrl
}

// Usage:
const imageUrl = urlFor(image.asset, image.asset.originalFilename)

Important Notes

• The vanity filename doesn't have to match the originalFilename – you can use any SEO-friendly name you want, or even add a custom field to your image schema for this purpose
• All the usual image transformation parameters (format, quality, dimensions, etc.) continue to work normally
• This feature isn't extensively documented yet (as mentioned in this community answer), but it's fully supported by the CDN

The hash-based filename is actually a feature, not a bug – it enables Sanity's content-addressable storage system where the URL itself is derived from the content, making cache invalidation automatic and bulletproof. The vanity filename gives you the best of both worlds: reliable caching and SEO-friendly URLs.