Import and export content > Import space from Contentful

Import space from Contentful

If you want to try DatoCMS, but you created your existing project with Contentful, you can use our command-line tool to import all content from a Contentful space to a DatoCMS project.

Setup

First install the @datocms/cli npm package:

Terminal window
npm install -g @datocms/cli

The package exposes the datocms CLI command, that you can use to install the Contentful importer plugin:

Terminal window
datocms plugins:install @datocms/cli-plugin-contentful

What you will need

To copy your Contentful space to DatoCMS, you will need the following information:

Your Contentful Space ID: you can find it under Settings > General settings:

A Contentful content management token: you can create one under Settings > API keys and then clicking the Add API key button:

Your DatoCMS full-access API token: create a new project, and then head to Project settings > API tokens:

Run the import

To import all the entries and assets of your Contentful space into DatoCMS, run the following in the console, making sure to replace the placeholder values with the tokens and IDs of your project:

Terminal window
rm -rf ./api-calls && datocms contentful:import \
--api-token=<apiToken> \
--contentful-token=<apiToken> \
--contentful-space-id=<spaceId> \
--log-level=BODY_AND_HEADERS \
--log-mode=directory

By specifying the log-level and log-mode options, a complete list of API calls made both to Contentful and DatoCMS will be generated in the ./api-calls folder, one per file, in chronological order. This information can be of great help if something should go wrong during the import.

If desired, you can also specify the --ignore-errors option, which will attempt to continue with the import process even if it encounters errors along the way.

The required parameters are these:

Terminal window
--api-token=<value> Your DatoCMS project read-write API token
--contentful-space-id=<value> Your Contentful space ID
--contentful-token=<value> Your Contentful read-write API token

To view the full list of options, you can always run the command:

Terminal window
datocms contentful:import --help

Known limitations

Although highly compatible, there are some minor differences between the types of fields that Contentful offers compared to DatoCMS, so the tool will follow these migration rules:

  • DatoCMS doesn't provide an array of strings field, so data of this kind will be converted in a single string field with comma separated values;

  • Contentful API doesn't expose presentation settings for fields, so all text fields will be set as Markdown editors (you will be able to change the presentation mode later from the DatoCMS interface);

  • DatoCMS doesn't allow a multi-paragraph text field to be the Model title, so if that's the case, no title field will be set;

  • While Contentful's reference field allows not specifying the list of content types that can be referenced, DatoCMS instead requires an explicit list. Therefore, in these cases, the task will set the entire catalog of models as the explicit list.