repository·main·Indexed 41 days ago
https://github.com/contentful/contentful-exportA Node.js library and CLI tool for backing up Contentful Content Models, Content, and Assets, or moving them between spaces. It exports space data to a JSON dump using the Contentful Management API (CMA) or Content Delivery API (CDA). It supports Experience Orchestration (ExO) entities, Contentful Releases, and embargoed assets. Requires Node.js 22 or later.
contentful-export is a Node.js library and CLI tool designed to export a Contentful space or environment's full content model, content, and assets into a single JSON file. It orchestrates paginated reads from the Contentful Management API (CMA) and optionally the Content Delivery API (CDA), downloads asset files to the local filesystem, and uses streaming JSON serialization to handle large datasets without memory exhaustion.If your space has the exo_m1 Organization entitlement, you can export Experience Orchestration entities by setting includeExperienceOrchestration: true.
This will fetch six specific entity types:
These are fetched using cursor-based pagination. If a space is not entitled to ExO, the tool will return empty arrays for these types rather than failing the entire export.
Experiences and Experience Fragments support Optimization Variants for personalization. These are not exported as a separate top-level array, but are instead nested within their parent objects as experience.optimizationVariants or experienceFragment.optimizationVariants because variants do not have globally-unique sys.ids.
To include these variants, you must explicitly set includeExoVariants: true. If omitted or set to false, the optimizationVariants field will be absent from the output.
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
includeExperienceOrchestration: true,
includeExoVariants: true
}
await contentfulExport(options)The export produces a JSON object containing arrays for various Contentful entities. The structure includes standard entities like contentTypes, entries, and assets, as well as Experience Orchestration (ExO) entities if includeExperienceOrchestration is enabled.
{
"contentTypes": [],
"entries": [],
"assets": [],
"locales": [],
"tags": [],
"webhooks": [],
"roles": [],
"editorInterfaces": [],
"releases": [],
"designTokens": [],
"components": [],
"experienceTemplates": [],
"dataAssemblies": [],
"experienceFragments": [],
"experiences": []
}Contentful Releases (a separate GA feature from ExO) can be included in your export.
Behavioral Rules:
skipReleases: false).Release.v2 (*.secure.* domains (embargoed assets) require JWT-signed URLs for access. When downloadAssets is enabled, the tool automatically uses the asset_keys API to create short-lived signed URLs (with a 6-hour expiry window) to ensure the binary files can be successfully streamed to your local disk.Experience Orchestration (ExO) is a system for composing page experiences using six entity types: designTokens, components, experienceTemplates, dataAssemblies, experienceFragments, and experiences.
Key behaviors:
includeExperienceOrchestration: true).exoM1 entitlement on the source space's organization. If the entitlement is missing, the tool logs a warning and exports an empty array for each entity type rather than failing.@internal and experimental; their structure may change.contentful-import, which handles dependency ordering (topological sort) for Components and Experience Fragments.The tool can fetch data using two different APIs, which changes the scope of the export:
deliveryToken. This mode fetches only the published versions of entries and assets. This is useful for lightweight, published-only snapshots. Note that tags will not be exported when using CDA.ExO Optimization Variants are nested directly onto their parent Experience or ExperienceFragment to avoid sys.id collisions. A variant is identified by its sys.variant (a server-generated UUID), sys.variantType, and sys.variantDimension.
{
"experiences": [
{
"sys": { "id": "abc123", "type": "Experience", "variant": "default", "variantType": "default" },
"name": "Homepage",
"optimizationVariants": [
{
"sys": { "id": "abc123", "type": "Experience", "variant": "f3a1...", "variantType": "personalization" },
"name": "Homepage (Variant A)"
}
]
}
],
"experienceFragments": [
{
"sys": { "id": "def456", "type": "ExperienceFragment" },
"name": "Hero Banner",
"optimizationVariants": []
}
]
}The contentful-export package requires Node.js 22 or later.
If you are running an environment with a Node.js version older than 22, you cannot use the current version of this package and must stay on the previous major version to maintain compatibility.
Optimization Variants are alternate versions of Experiences and Experience Fragments used for personalization. Because variants share the same sys.id as their parent, they are not exported as a top-level array. Instead, they are nested within their parent entity under an optimizationVariants field.
To include these variants in your export, you must explicitly set includeExoVariants: true. This is a separate opt-in from includeExperienceOrchestration and defaults to false.
false (default): The optimizationVariants field is absent from the parent objects.true: Every Experience and Experience Fragment includes an optimizationVariants array (even if empty []).const result = await contentfulExport({
spaceId: '<space_id>',
managementToken: '<management_token>',
includeExperienceOrchestration: true,
includeExoVariants: true,
})Experience Orchestration (ExO) entities (Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences) can be included in your export by passing includeExperienceOrchestration: true to the runContentfulExport function.
If your Contentful Organization does not have the required entitlement for ExO, the export will not fail; instead, the corresponding entity arrays will be returned as empty [] and a warning will be logged. This allows you to safely use this flag across different spaces.
import contentfulExport from 'contentful-export'
const result = await contentfulExport({
spaceId: '<space_id>',
managementToken: '<management_token>',
includeExperienceOrchestration: true,
})
// result will contain:
// result.designTokens — array of Design Token entities
// result.components — array of Component entities
// result.experienceTemplates — array of Experience Template entities
// result.dataAssemblies — array of Data Assembly entities
// result.experienceFragments — array of Experience Fragment entities
// result.experiences — array of Experience entities