Contentful provides a content infrastructure for digital teams to power content in websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship digital products faster.
This is a library that helps you backup your Content Model, Content and Assets or move them to a new Contentful space. It will support Roles & Permissions in a future version.
To import your exported data, please refer to the contentful-import repository.
We moved the CLI version of this tool into our Contentful CLI. This allows our users to use and install only one single CLI tool to get the full Contentful experience.
Please have a look at the Contentful CLI export command documentation to learn more about how to use this as command line tool.
- Node LTS
npm install contentful-exportconst contentfulExport = require('contentful-export')
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
...
}
contentfulExport(options)
.then((result) => {
console.log('Your space data:', result)
})
.catch((err) => {
console.log('Oh no! Some errors occurred!', err)
})import contentfulExport from 'contentful-export'
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
...
}
// contentfulExport returns a Promise so you can use async/await, etc.
await contentfulExport(options)To scope your export, you are able to pass query parameters. All search parameters of our API are supported as documented in our API documentation.
const contentfulExport = require('contentful-export')
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
queryEntries: ['content_type=<content_type_id>']
}
contentfulExport(options)
...The Export tool also support multiple inline queries.
const contentfulExport = require('contentful-export')
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
queryEntries: [
'content_type=<content_type_id>',
'sys.id=<entry_id>'
]
}
contentfulExport(options)
...queryAssets uses the same syntax as queryEntries
const contentfulExport = require('contentful-export')
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
environmentId: '<environment_id>'
}
contentfulExport(options)
...ID of the space with source data
ID of the environment in the source space
Contentful management API token for the space to be exported
Contentful Content Delivery API (CDA) token for the space to be exported.
Providing deliveryToken will export both entries and assets from the
Contentful Delivery API, instead of the Contentful Management API.
This may be useful if you want to export the latest published versions,
as the management API always only exports the entirety of items, with the latest
unpublished content. So if you want to make sure only to see the latest
published changes, provide the deliveryToken.
Just to clarify: When Contentful Management API always returns the latest version (e.g. 50 in this case):
"createdAt": "2020-01-06T12:00:00.000Z",
"updatedAt": "2020-04-07T11:00:00.000Z",
"publishedVersion": 23,
"publishedAt": "2020-04-05T14:00:00.000Z",
"publishedCounter": 1,
"version": 50,
the Content Delivery API would return the publishedVersion (23). CDA responses don't include
version number.
Note: Tags are only available on the Contentful Management API, so they will not be exported if you provide a Contentful Delivery Token. Tags is a new feature that not all users have access to.
Defines the path for storing the export JSON file
Save the export as a JSON file
The filename for the exported data
Include drafts in the exported entries.
The deliveryToken option is ignored
when includeDrafts has been set as true.
If you want to include drafts, there's no point of getting them through the
Content Delivery API.
Include archived entries in the exported entries
Skip exporting content models
Skip exporting editor interfaces
Skip exporting assets and entries.
Skip exporting roles and permissions
Skip exporting tags
Skip exporting webhooks
Untag assets and entries
Only export entries and assets
Only export entries that match these queries
Only export assets that match these queries
Download actual asset files
The Management API host
The Delivery API host
Proxy configuration in HTTP auth format: host:port or user:password@host:port
Pass proxy config to Axios instead of creating a custom httpsAgent
The number of items per page per request
Additional headers to attach to the requests.
Full path to the error log file
Display progress in new lines instead of displaying a busy spinner and the status in the same line. Useful for CI.
Flag controlling whether Experience Orchestration (ExO) entities — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — are exported when present in the source space. Requires the exoM1 entitlement on the source space's organization. Set to false to opt out. See the "Experience Orchestration (ExO) entities" section below for what happens when the space isn't entitled.
Unable to connect to Contentful through your proxy? Try to set the rawProxy option to true.
contentfulExport({
proxy: 'https://cat:dog@example.com:1234',
rawProxy: true,
...
})Contentful response sizes are limited (find more info in our technical limit docs). In order to resolve this issue, limit the amount of entities received within a single request by setting the maxAllowedLimit option:
contentfulExport({
proxy: 'https://cat:dog@example.com:1234',
rawProxy: true,
maxAllowedLimit: 50
...
})If a space is configured to use the embargoed assets feature, certain options will need to be set to use the export/import tooling. When exporting content, the downloadAssets option must be set to true. This will download the asset files to your local machine. Then, when importing content (using contentful-import), the uploadAssets option must be set to true and the assetsDirectory must be set to the directory that contains all of the exported asset folders.
const contentfulExport = require("contentful-export");
const options = {
spaceId: "<space_id>",
managementToken: "<content_management_api_key>",
downloadAssets: true,
};
contentfulExport(options);This is an overview of the exported data:
{
"contentTypes": [],
"entries": [],
"assets": [],
"locales": [],
"tags": [],
"webhooks": [],
"roles": [],
"editorInterfaces": [],
"designTokens": [],
"components": [],
"experienceTemplates": [],
"dataAssemblies": [],
"experienceFragments": [],
"experiences": []
}Note: Tags feature is not available for all users. If you do not have access to this feature, the tags array will always be empty.
Note: designTokens, components, experienceTemplates, dataAssemblies, experienceFragments, and experiences are Experience Orchestration (ExO) entities — present by default; absent only if you explicitly set includeExperienceOrchestration: false — see the "Experience Orchestration (ExO) entities" section below.
Experience Orchestration (ExO) is Contentful's system for composing and rendering structured page experiences. It sits above the traditional entry/content-type layer and provides six dedicated entity types — Design Tokens, Components, Experience Templates, Data Assemblies, Experience Fragments, and Experiences — that together describe how content is fetched, assembled, and laid out.
Experimental: ExO entities (
designTokens,components,experienceTemplates,dataAssemblies,experienceFragments,experiences) are@internaland considered experimental. Their shape and export behavior are subject to change without notice.
ExO export is on by default (includeExperienceOrchestration: true) — for the CLI and the module API alike. Pass includeExperienceOrchestration: false (--include-experience-orchestration=false on the CLI) to opt out.
import contentfulExport from 'contentful-export'
const options = {
spaceId: '<space_id>',
managementToken: '<content_management_api_key>',
includeExperienceOrchestration: false // opt out; omit to export ExO entities when present (the default)
}
await contentfulExport(options)If the source space has no ExO entities, or lacks the exoM1 entitlement, each ExO entity type logs a Skipping <Entity> export warning and exports as an empty array — it does not fail the export. Pass includeExperienceOrchestration: false if you want to avoid it.
Requires the exoM1 entitlement on the source space's organization. contentful-cli's space export command doesn't expose this option at all yet, so ExO export isn't reachable through that separate CLI regardless of default.
The ExO entities exported here are designed to be fed directly into contentful-import, which preserves source IDs, applies dependency ordering (a topological sort for Components and Experience Fragments, since either can reference others of the same type), and upgrades entities from older, pre-rename export files automatically. See contentful-import's README "Experience Orchestration (ExO) entities" section for the import-side details.
- This tool currently does not support the export of space memberships.
- Exported webhooks with credentials will be exported as normal webhooks. Credentials should be added manually afterwards.
- If you have custom UI extensions, you need to reinstall them manually in the new space.
Read the releases page for more information.
This project is licensed under MIT license
If you are an AI coding agent working in this repository, read AGENTS.md first. It tells you where to find architectural context, development setup, decision records, and repo-specific rules.