Contentful import tool

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 library helps you to import files generated by contentful-export to a destination space.

:exclamation: Usage as CLI

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 import command documentation to learn more about how to use this as command line tool.

:cloud: Pre-requisites && Installation

Pre-requisites

• Node >= 22

Installation

npm install contentful-import

:hand: Usage as a module

const contentfulImport = require('contentful-import')

const options = {
  content: {entries:..., contentTypes:..., locales:...},
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  ...
}

contentfulImport(options)
  .then(() => {
    console.log('Data imported successfully')
  })
  .catch((err) => {
    console.log('Oh no! Some errors occurred!', err)
  })

Using ESM:

import spaceImport from "contentful-import";

or

const contentfulImport = require('contentful-import')

const options = {
  contentFile: '/path/to/result/of/contentful-export.json',
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  ...
}

contentfulImport(options)
  .then(() => {
    console.log('Data imported successfully')
  })
  .catch((err) => {
    console.log('Oh no! Some errors occurred!', err)
  })

💾 Usage as a CLI executable

1. Build the package:

$ npm run build

2. Execute the CLI tool by running the binary and passing the required parameters

$ ./bin/contentful-cli \
--space-id <space-id> \
--management-token <management-token> \
--content-file <content-file>

Import an environment

const contentfulImport = require('contentful-import')

const options = {
  contentFile: '/path/to/result/of/contentful-export.json',
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  environmentId: '<environment_id>',
  ...
}

contentfulImport(options)
...

:gear: Configuration options

Basics

spaceId [string] [required]

ID of the space to import into

environmentId [string] [default: 'master']

ID of the environment in the destination space

managementToken [string] [required]

Contentful management API token for the space to be imported to

contentFile [string]

Path to JSON file that contains data to be import to your space

content [object]

Content to import. Needs to match the expected structure (See below)

Filtering

contentModelOnly [boolean] [default: false]

Import content types only

skipContentModel [boolean] [default: false]

Skip importing of content types and locales

skipLocales [boolean] [default: false]

Skip importing of locales

skipContentUpdates [boolean] [default: false]

Skip updating existing content

skipContentPublishing [boolean] [default: false]

Skips content publishing. Creates content but does not publish it

Assets

uploadAssets [boolean] [default: false]

Upload local asset files downloaded via the downloadAssets option of the export. Requires assetsDirectory

skipAssetUpdates [boolean] [default: false]

Skip updating existing assets

assetsDirectory [string]

Path to a directory with an asset export made using the downloadAssets option of the export. Requires uploadAssets

timeout [number] [default: 3000]

Time between retries on asset processing

retryLimit [number] [default: 10]

Maximum number of retries for asset processing

Connection

host [string] [default: 'api.contentful.com']

The Management API host

proxy [string]

Proxy configuration in HTTP auth format: host:port or user:password@host:port

rawProxy [boolean]

Pass proxy config to Axios instead of creating a custom httpsAgent

rateLimit [number] [default: 7]

Maximum requests per second used for API requests

headers [object]

Additional headers to attach to the requests.

Other

errorLogFile [string]

Full path to the error log file

useVerboseRenderer [boolean] [default: false]

Display progress in new lines instead of displaying a busy spinner and the status in the same line. Useful for CI.

config [string]

Path to a JSON file with the configuration options. This file will be merged with the options passed to the function. The options passed to the function will take precedence over the ones in the config file.

Experience Orchestration

includeExperienceOrchestration [boolean] [default: true]

Flag controlling whether Experience Orchestration (ExO) entities — Design Tokens, Components, Experience Templates, Experience Fragments, Data Assemblies, and Experiences — are imported when present in the source content. Requires the exoM1 entitlement on the destination space's organization. Set to false to opt out. See the "Experience Orchestration (ExO) entities" section below for what happens when the destination isn't entitled.

:rescue_worker_helmet: Troubleshooting

Proxy

Unable to connect to Contentful through your Proxy? Try to set the rawProxy option to true.

contentfulImport({
  proxy: 'https://cat:[email protected]:1234',
  rawProxy: true,
  ...
})

Embargoed Assets

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 (using contentful-export), the downloadAssets option must be set to true. This will download the asset files to your local machine. Then, when importing content, 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 contentfulImport = require('contentful-import')

const options = {
  contentFile: '/path/to/result/of/contentful-export.json',
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  uploadAssets: true,
  assetsDirectory: '/path/to/exported/assets.json'
}

contentfulImport(options)

:card_file_box: Expected input data structure

The data to import should be structured like this:

{
  "contentTypes": [],
  "entries": [],
  "assets": [],
  "locales": [],
  "webhooks": [],
  "roles": [],
  "tags": [],
  "editorInterfaces": [],
  "designTokens": [],
  "components": [],
  "experienceTemplates": [],
  "dataAssemblies": [],
  "experienceFragments": [],
  "experiences": []
}

Note: tags are not available for all users. If you do not have access to this feature, any tags included in your import data will be skipped.

The designTokens, components, experienceTemplates, dataAssemblies, experienceFragments, and experiences keys are Experience Orchestration (ExO) entities — see the "Experience Orchestration (ExO) entities" section below.

:test_tube: Experience Orchestration (ExO) entities

Experimental: ExO entities (designTokens, components, experienceTemplates, dataAssemblies, experienceFragments, experiences) are @internal and considered experimental. Their shape and import behavior are subject to change without notice.

ExO import 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 contentfulImport from 'contentful-import'

const options = {
  contentFile: '/path/to/result/of/contentful-export.json',
  spaceId: '<space_id>',
  managementToken: '<content_management_api_key>',
  includeExperienceOrchestration: false, // opt out; omit to import ExO entities when present (the default)
  ...
}

await contentfulImport(options)

If your source content has no ExO entities at all — true for anyone not using ExO — this default is a complete no-op. The destination-entitlement check in lib/tasks/get-destination-data.ts only runs if the source data actually contains ExO entities (sourceData.designTokens?.length, etc.); with nothing to check, no extra API calls happen and nothing extra gets logged. Behavior is identical either way for imports that don't involve ExO content.

Requires the exoM1 entitlement on the destination space's organization. contentful-cli's space import command doesn't expose this option at all yet, so ExO import isn't reachable through that separate CLI regardless of default.

If the destination space isn't entitled and the source data does contain ExO entities, ExO import for that space is skipped and the rest of the content (content types, entries, assets, etc.) still imports normally — but the missing-entitlement notice is logged at error level, not warning. That means contentfulImport() still rejects with a ContentfulMultiError at the end, even though the non-ExO content imported successfully. Don't treat a rejected promise as proof the whole import failed — check err.errors (or the errorLogFile) for Experience Orchestration (ExO) is not enabled for this space before assuming something is actually broken.

Import order

ExO entities are created and published in dependency order, then unpublished in reverse order once every other import step has finished:

1. Data Assemblies — create, then publish
2. Design Tokens — create only (no publish/unpublish step; a Design Token is live as soon as it's created or updated)
3. Components — create, then publish
4. Experience Templates — create, then publish
5. Experience Fragments — create, then publish
6. Experiences — create, then publish
7. Unpublish pass, in reverse: Experiences → Experience Fragments → Experience Templates → Components → Data Assemblies

An entity that's published in the source is published in the destination on import. An entity that's unpublished (or removed) in the source but still published in the destination is unpublished on re-import — this propagates in both directions, so reverting a published ExO entity back to draft in the source and re-running the import will unpublish it in the destination too.

URN rewriting / backward compatibility

• Export files taken before the ExO entity rename (ComponentType → Component, Fragment → ExperienceFragment, Template → ExperienceTemplate) are upgraded automatically on import, including the corresponding resource-link linkTypes and URN path segments. This upgrade is upgrade-only (there's no downgrade path) and idempotent, so it's safe to run against already-upgraded data.
• Export files that predate ExO entirely (no ExO keys, or empty ExO arrays) import unchanged — no extra configuration is needed to import older export files.

:bulb: Importing to a space with existing content

• Both source space and destination space must share the same content model structure. In order to achieve that, please use contentful-migration.
• Content transformations are also not supported, please use contentful-migration.
• Entities existence are determined based on their ID:
  • If an entity does not exist in the destination space, it will be created.
  • If an entity already exists in the destination space, it will be updated.
• Publishing strategy:
  • If an entity is in draft, it will be created as draft in the destination space.
  • If an entity is published and has pending changes (updated) in the source space, it will be published with the latest changes in the destination space.

:warning: Limitations

• This tool currently does not support the import of space memberships.
• This tool currently does not support the import of roles.
• This tool is expecting the target space to have the same default locale as your previously exported space.
• Imported webhooks with credentials will be imported as normal webhooks. Credentials should be added manually afterwards.
• Imported webhooks with secret headers will be imported without these headers. Secret headers should be added manuall afterwards.
• If you have custom UI extensions, you need to reinstall them manually in the new space.

:memo: Changelog

Read the releases page for more information.

:scroll: License

This project is licensed under MIT license

For AI Agents

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.