npm package: @itxch/contentful-import
Description: This tool allows you to import JSON dump exported by contentful-export
Author: Contentful
Latest version: 1.0.1

# Contentful import tool

[![npm](https://img.shields.io/npm/v/contentful-import.svg)](https://www.npmjs.com/package/contentful-import)
[![CircleCI](https://circleci.com/gh/contentful/contentful-import.svg?style=shield)](https://circleci.com/gh/contentful/contentful-import/?branch=master)

[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)

[Contentful](https://www.contentful.com) 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](https://github.com/contentful/contentful-export) to a destination space.

## :exclamation: Usage as CLI

> We moved the CLI version of this tool into our [Contentful CLI](https://github.com/contentful/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](https://github.com/contentful/contentful-cli/tree/master/docs/space/import) to learn more about how to use this as command line tool.

## :cloud: Pre-requisites && Installation

### Pre-requisites

- Node LTS (v22 or higher)

### Installation

```bash
npm install contentful-import
```

## :hand: Usage

```javascript
import contentfulImport from 'contentful-import';

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

try {
  await contentfulImport(options);
  console.log('Data imported successfully');
} catch (err) {
  console.log('Oh no! Some errors occurred!', err);
}
```

The package also supports CommonJS imports:

```javascript
const contentfulImport = require('contentful-import');
```

Or point to a JSON file that contains the data to import:

```javascript
import contentfulImport from 'contentful-import';

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

try {
  await contentfulImport(options);
  console.log('Data imported successfully');
} catch (err) {
  console.log('Oh no! Some errors occurred!', err);
}
```

#### Import an environment

```javascript
import contentfulImport from 'contentful-import';

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

try {
  await contentfulImport(options);
  console.log('Environment imported successfully');
} catch (err) {
  console.log('Oh no! Some errors occurred!', err);
}
```

## :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](https://github.com/contentful/contentful-export#downloadassets-boolean) 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](https://github.com/contentful/contentful-export#downloadassets-boolean) 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.

## :rescue_worker_helmet: Troubleshooting

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

```javascript
contentfulImport({
  proxy: 'https://cat:dog@example.com:1234',
  rawProxy: true,
  ...
})
```

## :card_file_box: Expected input data structure

The data to import should be structured like this:

```json
{
  "contentTypes": [],
  "entries": [],
  "assets": [],
  "locales": [],
  "webhooks": [],
  "roles": [],
  "tags": [],
  "editorInterfaces": []
}
```

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.

## :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](https://www.npmjs.com/package/contentful-migration).
- Content transformations are also not supported, please use [contentful-migration](https://www.npmjs.com/package/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](https://github.com/contentful/contentful-import/releases) page for more information.

## :scroll: License

This project is licensed under MIT license

[1]: https://www.contentful.com