Playground

Contentful Playground

Native SDK + API Proxy

Run real requests through the Cachely edge proxy and see how server-side token injection, edge caching, asset URL rewriting, preview bypass, and AI transforms work for Contentful.

Open docs

Full API proxy demo — query Contentful entries through the edge proxy with credentials hidden from the client and asset URLs rewritten.

API requests proxied through /~apiSpace-aware asset URL rewritingToken never leaves the edgePreview bypass support

Integration facts (verified against the SDK)

SDK module
@cachely-io/sdk/contentful
Built-in provider id
Yes — provider: 'contentful' is registered
Real SDK exports used
createContentfulCachelyAdaptercreateCachelyContentfulClientcreateCachelyFetch
CLI setup
Wires createContentfulCachelyAdapter into your existing contentful.createClient.

Recommended: createContentfulCachelyAdapter as the contentful.createClient adapter

✓ Supported ◐ Partial — Not applicable
Native SDK + API Proxy
  • ✓

    API proxy

    Supported
    What it does
    Routes CMS API calls through the Cachely edge.
    Use it for
    Hiding tokens, caching CMS responses, using one tenant domain.
    Benefit
    Faster repeated reads, safer public apps, unified delivery.
  • ✓

    Server-side token injection

    Supported
    What it does
    Keeps CMS credentials on the edge/server side.
    Use it for
    APIs that normally require private tokens.
    Benefit
    The token never ships to the browser.
  • ✓

    Edge cache

    Supported
    What it does
    Caches CMS/API responses at the edge.
    Use it for
    Repeated content reads and high-traffic pages.
    Benefit
    Lower origin/CMS usage, faster responses, better resilience.
  • ✓

    Asset URL rewriting

    Supported
    What it does
    Rewrites CMS asset URLs inside JSON responses to your tenant domain.
    Use it for
    Serving images/assets from the same delivery layer.
    Benefit
    Fewer third-party domains, edge delivery, simpler security policy.
  • ✓

    Preview / bypass mode

    Supported
    What it does
    Skips the cache for fresh CMS/editor preview content.
    Use it for
    Preview flows, draft content, editor QA.
    Benefit
    Editors see fresh content without disabling production cache.
  • ✓

    AI transforms

    Supported
    What it does
    Applies a named AI transform profile to eligible JSON/text responses.
    Use it for
    Localization, summaries, formatting, content adaptation.
    Benefit
    Transform responses without changing the CMS or app code.
  • ✓

    Native SDK integration

    Supported
    What it does
    Wraps the provider SDK and automatically proxies its requests.
    Use it for
    Nuxt/Next apps that already use the CMS SDK.
    Benefit
    Minimal code changes, safer defaults.

Integration

Ways to connect Contentful

The recommended paths for Contentful are shown first. Less common options are tucked under “Other options”.

CLI setup

Recommended

Recommended for Nuxt/Next — npx @cachely-io/sdk setup auto-detects your framework and wires the native Contentful integration.

Code changes
None by hand — the CLI generates them.
Cachely handles
Framework + CMS detection, native client/composable wiring, env + proxy config.
Terminal
npx @cachely-io/sdk setup

Contentful SDK + Cachely adapter

Recommended

Best for existing Contentful projects — keep your contentful.createClient and route requests through Cachely via the adapter. It only activates when CACHELY_PROXY_URL is set.

Code changes
Add adapter: createContentfulCachelyAdapter({ proxyUrl }) to your createClient config.
Cachely handles
Proxying, asset URL rewriting, and AI transforms. Your existing Contentful credentials still apply; the edge handles delivery.

Limitations: createCachelyContentfulClient also exists but targets the chainable v10+ client API; the adapter is the recommended path and matches the CLI.

TypeScript
const contentful = require('contentful')
const { createContentfulCachelyAdapter } = require('@cachely-io/sdk/contentful')

const cachelyProxyUrl = process.env.CACHELY_PROXY_URL

const config = {
  space,
  accessToken,
  host,
  // Route through Cachely only when CACHELY_PROXY_URL is set; otherwise the
  // client talks to Contentful directly (unchanged behavior).
  ...(cachelyProxyUrl
    ? { adapter: createContentfulCachelyAdapter({ proxyUrl: cachelyProxyUrl }) }
    : {}),
}

module.exports = {
  createClient () {
    return contentful.createClient(config)
  },
}
  • createContentfulCachelyAdapter keeps your normal Contentful client — you only swap the adapter, so call sites and types stay the same.
  • The adapter activates only when CACHELY_PROXY_URL is set; without it the client talks to Contentful directly (unchanged behavior).
Mode:Standard proxied request with edge cache

Request controls

Preset:

Original

https://cdn.contentful.com/spaces/abc123/entries?content_type=page&limit=3

Proxied (preview)

https://demo-contentful.cachely.io/~api/spaces/abc123/entries?content_type=page&limit=3

Sends this request through demo-contentful.cachely.io. Cachely injects the token server-side, rewrites eligible asset URLs, and returns cache debug headers.

Fetch modes

Direct

Standard proxied request. Best for production traffic — the edge cache serves repeat reads.

Bypass Cache

Adds ?preview=1 so the proxy returns fresh content. Use for CMS preview/editor flows.

AI Transform

Applies a named profile to eligible JSON/text content. Transformed responses are cached separately. Skipped for metadata endpoints.

Integration: Uses @cachely-io/sdk/contentful. The access token is injected server-side.

SDK Referenceupdates as you change modes
contentful + @cachely-io/sdk/contentful
import { createClient } from 'contentful'
import { createContentfulCachelyAdapter } from '@cachely-io/sdk/contentful'

const cachelyProxyUrl = process.env.CACHELY_PROXY_URL

export const client = createClient({
  space: 'abc123',
  accessToken: process.env.CONTENTFUL_TOKEN!,
  // Route through Cachely only when CACHELY_PROXY_URL is set:
  ...(cachelyProxyUrl
    ? { adapter: createContentfulCachelyAdapter({ proxyUrl: cachelyProxyUrl, spaceId: 'abc123' }) }
    : {}),
})

const entries = await client.getEntries({ content_type: 'page' })
Contentful — Access token is injected server-side by the proxy. Set accessToken to any truthy string (e.g. "proxy-injected") to satisfy SDK validation.

SDK snippets

Contentful code examples

Copy-paste examples for Contentful. Pick a variant below.

Best for existing Contentful projects — keep contentful.createClient and route through Cachely via the adapter. Activates only when CACHELY_PROXY_URL is set.

Adapter (CommonJS)
const contentful = require('contentful')
const { createContentfulCachelyAdapter } = require('@cachely-io/sdk/contentful')

const cachelyProxyUrl = process.env.CACHELY_PROXY_URL

const config = {
  space,
  accessToken,
  host,
  // Route through Cachely only when CACHELY_PROXY_URL is set; otherwise the
  // client talks to Contentful directly (unchanged behavior).
  ...(cachelyProxyUrl
    ? { adapter: createContentfulCachelyAdapter({ proxyUrl: cachelyProxyUrl }) }
    : {}),
}

module.exports = {
  createClient () {
    return contentful.createClient(config)
  },
}