contentful.js

When using the withAllLocales client chain modifier, the response type is adjusted to include all existing locales in your space.

• For getAsset and getAssets, you can provide an optional generic parameter for the locales.
• For parseEntries, getEntry, and getEntries, you can provide an optional second generic parameter for the locales.

If a Locale type is provided, field values will be mapped to the locale keys (e.g., fieldValue: { 'en-US': 'value', 'de-DE': 'value' }).

import * as contentful from 'contentful'

const client = contentful.createClient({
  space: '<space-id',
  accessToken: '<content-delivery-token>',
})

type ProductEntrySkeleton = {
  fields: { productName: contentful.EntryFieldTypes.Text }
  contentTypeId: 'product'
}
type Locales = 'en-US' | 'de-DE'
const entry = client.withAllLocales.getEntry<ProductEntrySkeleton, Locales>('some-entry-id')

Introduced in v10.0.0, client chain modifiers allow you to change the shape of the data returned by methods like getEntries, getEntry, getAssets, getAsset, sync, and parseEntries. This provides better type support and predictable data structures.

Entries Modifiers

Used with getEntries, getEntry, and parseEntries.

• withAllLocales: Returns entries in all locales.
• withoutLinkResolution: All linked entries will be rendered as link objects.
• withoutUnresolvableLinks: Removes link objects if the linked entries are not resolvable.
• withLocaleBasedPublishing: Returns only content from published locales.
• Default: Returns entries in a single locale with resolvable links inlined.

Assets Modifiers

Used with getAssets and getAsset.

• withAllLocales: Returns assets in all locales.
• Default: Returns assets in a single locale.

Sync Modifiers

Used with sync. Note that withAllLocales is accepted but ignored because the Sync API always retrieves all localized content.

• withoutLinkResolution: Linked content will be rendered as link objects.
• withoutUnresolvableLinks: Removes link objects if the linked content is not resolvable.
• Default: Returns content in all locales.

You can chain multiple modifiers together.

// returns entries in one locale, resolves linked entries, removing unresolvable links
const entries = await client.withoutUnresolvableLinks.getEntries()

// returns entries in all locales, resolves linked entries, removing unresolvable links
const entries = await client.withoutLinkResolution.withAllLocales.getEntries()

// returns parsed entries in all locales
const entries = client.withAllLocales.parseEntries(localizedData)

// returns assets in all locales
const assets = await client.withAllLocales.getAssets()

// returns content in all locales, resolves linked entries, removing unresolvable links
const { entries, assets, deletedEntries, deletedAssets } =
  await client.withoutUnresolvableLinks.sync({ initial: true })

The withoutUnresolvableLinks client chain modifier ensures that the returned type does not include linked entries that cannot be resolved (e.g., if the linked entity is deleted or not yet published). In these cases, the field will effectively be empty in the resulting object.

import * as contentful from 'contentful'

const client = contentful.createClient({
  space: '<space-id>',
  accessToken: '<content-delivery-token>',
})

type ProductEntrySkeleton = {
  contentTypeId: 'product'
  fields: {
    productName: contentful.EntryFieldTypes.Text
    image: contentful.EntryFieldTypes.AssetLink
    price: contentful.EntryFieldTypes.Number
  }
}

type ReferencedProductEntrySkeleton = {
  fields: { relatedProduct: contentful.EntryFieldTypes.EntryLink<ProductEntrySkeleton> }
  contentTypeId: 'referencedProduct'
}
const entry =
  client.withoutUnresolvableLinks.getEntry<ReferencedProductEntrySkeleton>('some-entry-id')

Version 10.0.0 is a TypeScript rewrite that replaces several configuration options and query parameters with client chain modifiers. This change provides better type support for different response shapes.

Replace resolveLinks and removeUnresolved

In v10.x, resolveLinks and removeUnresolved are no longer supported as client config options or query parameters for getEntries, getEntry, parseEntries, or initial sync calls.

• To disable link resolution (previously resolveLinks: false): Use .withoutLinkResolution before your method call.
• To remove unresolvable links (previously removeUnresolved: true): Use .withoutUnresolvableLinks before your method call.

Replace locale: '*'

In v10.x, setting the locale parameter to '*' is no longer supported for getEntries, getEntry, getAssets, getAsset, or initial sync calls.

• To fetch all locales: Use .withAllLocales before your method call.

Note: Setting a specific locale (e.g., locale: 'en-US') continues to work as before.