Storyblok Integration

CMS Assets has first-class support for Storyblok. It handles all regional CDN variants and provides a response transformer that rewrites asset URLs in your Storyblok API responses.

Supported URL patterns

Storyblok serves assets from regional CDN hosts. CMS Assets handles all of them:

Europe (default):

https://a.storyblok.com/f/123456/1920x1080/abc123def/photo.jpg

US:

https://a-us.storyblok.com/f/123456/1920x1080/abc123def/photo.jpg

Other regions: a-ap.storyblok.com, a-ca.storyblok.com, a2.storyblok.com

All are rewritten to your tenant URL:

https://your-tenant.cmsassets.com/1920x1080/abc123def/photo.jpg

Tenant setup

When creating your tenant, select Storyblok as the CMS type and provide your space ID:

Your numeric space ID can be found in the Storyblok dashboard under Settings → General.

Note: The space ID is the numeric identifier, not the space name. For example, if your asset URLs look like https://a.storyblok.com/f/123456/..., your space ID is 123456.

Response transformer

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

npm install @synchronized-studio/response-transformer

Basic usage

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

const response = await fetch(`https://api.storyblok.com/v2/cdn/stories?token=${token}`)
const data = await response.json()

const transformed = transformCmsAssetUrls(data, {
  cms: "storyblok",
  identifier: "123456",
  cmsAssetsUrl: "https://your-tenant.cmsassets.com"
})

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 = transformCmsAssetUrls(data, {
  cms: "storyblok",
  identifier: "123456"
})

Nuxt / SSR integration

For Nuxt or other SSR frameworks, wrap your Storyblok data layer:

// composables/useStoryblokData.ts
import { transformCmsAssetUrls } from "@synchronized-studio/response-transformer"

export async function useStoryblokData(slug: string) {
  const data = await storyblokApi.get(`cdn/stories/${slug}`)

  return transformCmsAssetUrls(data, {
    cms: "storyblok",
    identifier: "123456",
    cmsAssetsUrl: useRuntimeConfig().public.cmsAssetsUrl
  })
}

Advanced options

Regional CDN handling

If your Storyblok space is hosted in a specific region, CMS Assets automatically handles all regional CDN variants. No additional configuration is required — the edge worker matches URLs from any Storyblok CDN host (a.storyblok.com, a-us.storyblok.com, a-ap.storyblok.com, a-ca.storyblok.com, a2.storyblok.com).

Image optimization

Storyblok supports image transformations via URL parameters:

https://a.storyblok.com/f/123456/1920x1080/abc123/photo.jpg/m/600x400/filters:quality(80)

These transformation paths are preserved through the proxy:

https://your-tenant.cmsassets.com/1920x1080/abc123/photo.jpg/m/600x400/filters:quality(80)

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 = transformCmsAssetUrls(data, {
  cms: "storyblok",
  identifier: "123456",
  onError: (error) => {
    Sentry.captureException(error)
  }
})