Imgix Integration

CMS Assets has first-class support for Imgix. It proxies and caches your Imgix asset URLs and provides a response transformer that rewrites Imgix CDN URLs in your API responses.

Supported URL patterns

Imgix serves assets from your source domain, either the default *.imgix.net subdomain or a custom domain you've configured:

Standard source domain:

https://my-source.imgix.net/images/photo.jpg

With rendering parameters:

https://my-source.imgix.net/images/photo.jpg?w=800&h=600&fit=crop&auto=format

Custom subdomain:

https://images.your-site.com/images/photo.jpg?auto=format

These are rewritten to:

https://your-tenant.cmsassets.com/images/photo.jpg

Tenant setup

When creating your tenant, select Imgix as the CMS type and provide your Imgix source domain:

The origin is automatically configured from your source domain:

• Origin: https://my-source.imgix.net

If you use a custom subdomain (e.g. images.your-site.com) as your Imgix source, enter that as the Imgix domain instead.

Imgix Rendering API

Imgix applies image transformations via query parameters (e.g. ?w=800&h=600&fit=crop&auto=format). When assets are proxied through CMS Assets:

• The edge cache strips query parameters from the cache key for image types
• This means all transformation variants share the same cache entry
• If you rely on Imgix's rendering API for different sizes/crops, the first cached version will be served for all variants

If you need different image renditions, apply transformations on the client side or serve each variant from a different path.

Response transformer

Install the response transformer to automatically rewrite Imgix asset URLs in your API responses:

npm install @synchronized-studio/response-transformer

Basic usage

import { transformImgixAssetUrls } from "@synchronized-studio/response-transformer"

const data = await fetchYourCmsData()

const transformed = transformImgixAssetUrls(data, {
  imgixDomain: "my-source.imgix.net",
  cmsAssetsUrl: "https://your-tenant.cmsassets.com"
})

What gets transformed

The transformer processes the entire JSON response and rewrites all matching URLs. This includes:

• Any URL matching your Imgix source domain (my-source.imgix.net)
• URLs with rendering parameters (the parameters are stripped)
• Custom subdomain URLs if your Imgix source uses one

Query parameters (like Imgix's ?w=800&auto=format) are stripped during rewriting.

Using an environment variable

Set CMS_ASSETS_URL in your environment and omit the cmsAssetsUrl option:

CMS_ASSETS_URL=https://your-tenant.cmsassets.com

const transformed = transformImgixAssetUrls(data, {
  imgixDomain: "my-source.imgix.net"
})

Nuxt / SSR integration

For Nuxt or other SSR frameworks, wrap your data-fetching calls:

// composables/useImgixData.ts
import { transformImgixAssetUrls } from "@synchronized-studio/response-transformer"

export async function useImgixAssets() {
  const data = await fetchCmsData()

  return transformImgixAssetUrls(data, {
    imgixDomain: "my-source.imgix.net",
    cmsAssetsUrl: useRuntimeConfig().public.cmsAssetsUrl
  })
}

Using the generic transformer

You can also use the unified transformCmsAssetUrls function:

import { transformCmsAssetUrls } from "@synchronized-studio/response-transformer"

const transformed = transformCmsAssetUrls(data, {
  cms: "imgix",
  imgixDomain: "my-source.imgix.net",
  cmsAssetsUrl: "https://your-tenant.cmsassets.com"
})

Advanced options

Custom transformers

Add additional transformers that run after the default Imgix ones:

const transformed = transformImgixAssetUrls(data, {
  imgixDomain: "my-source.imgix.net",
  transformers: [
    (jsonStr, { base }) => {
      return jsonStr.replaceAll("old-pattern", "new-pattern")
    }
  ]
})

Post-transform hook

Run a function on the parsed result after all URL replacements:

const transformed = transformImgixAssetUrls(data, {
  imgixDomain: "my-source.imgix.net",
  postTransform: (data) => {
    return data
  }
})

Error handling

By default, transform errors are logged as warnings and the original data is returned unchanged. You can provide a custom error handler:

const transformed = transformImgixAssetUrls(data, {
  imgixDomain: "my-source.imgix.net",
  onError: (error) => {
    Sentry.captureException(error)
  }
})