contentful-migration - content model migration tool

Describe and execute changes to your content model and transform entry content.

What is Contentful?

Contentful provides content infrastructure for digital teams to power 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 their products faster.

Table of contents

• contentful-migration - content model migration tool
• Core Features
• Pre-requisites \&\& Installation
  • Pre-requisites
  • Installation
• Usage
• :exclamation: Usage as CLI
  • Usage as a library
• Documentation \& References
  • Configuration
  • Chaining vs Object notation
  • migration
  • createContentType(id[, opts]) : ContentType
  • editContentType(id[, opts]) : ContentType
  • deleteContentType(id)
  • transformEntries(config)
    • transformEntries Example
  • deriveLinkedEntries(config)
    • deriveLinkedEntries(config) Example
  • transformEntriesToType(config)
    • transformEntriesToType Example
  • createTag(id[, opts, visibility])
  • editTag(id[, opts])
  • deleteTag(id)
  • setTagsForEntries(config)
    • setTagsForEntries Example
  • context
  • makeRequest(config)
  • spaceId : string
  • accessToken : string
  • Content type
  • createField(id[, opts]) : Field
  • editField(id[, opts]) : Field
  • deleteField(id) : void
  • changeFieldId (currentId, newId) : void
  • moveField (id) : MovableField
  • changeFieldControl (fieldId, widgetNamespace, widgetId[, settings]) : void
  • resetFieldControl (fieldId) : void
  • copyFieldControl (sourceFieldId, destinationFieldId) : void
  • addSidebarWidget (widgetNamespace, widgetId[, settings, insertBeforeWidgetId]) : void
  • updateSidebarWidget (widgetNamespace, widgetId, settings) : void
  • removeSidebarWidget (widgetNamespace, widgetId) : void
  • resetSidebarToDefault () : void
  • configureEntryEditor (widgetNamespace, widgetId[, settings]) : void
  • configureEntryEditors (EntryEditor[]) : void
  • resetEntryEditorToDefault () : void
  • createEditorLayout () : EditorLayout
  • editEditorLayout () : EditorLayout
  • deleteEditorLayout () : void
  • setAnnotations(AnnotationId[])
  • clearAnnotations()
  • addTaxonomyValidation(id, linkType[, opts])
  • clearTaxonomyValidations()
  • setTaxonomyValidations(validations)
  • Field
  • setAnnotations(AnnotationId[])
  • clearAnnotations()
  • Editor Layout
  • moveField(id) : MovableEditorLayoutItem
  • createFieldGroup(id[, opts]) : EditorLayoutFieldGroup
  • deleteFieldGroup (id) : void
  • changeFieldGroupId (currentId, newId)
  • editFieldGroup (id[, opts]) : EditorLayoutFieldGroup
  • Editor Layout Field Group
  • createFieldGroup (id[, opts]) : EditorLayoutFieldGroup
  • changeFieldGroupControl (id, widgetNamespace, widgetId[, settings]) : void
• Validation errors
• Example migrations
• Writing Migrations in Typescript
• Troubleshooting
• Updating Integration tests fixtures
• Reach out to us
  • You have questions about how to use this library?
  • You found a bug or want to propose a feature?
  • You need to share confidential information or have other questions?
• Get involved
• License
• Code of Conduct

Core Features

• Content type
• Edit Content type
• Create a Content type
• Entries
• Transform Entries for a Given Content type
• Derives a new entry and sets up a reference to it on the source entry
• Updates tags on entries for a given Content Type
• Fields
• Create a field
• Edit a field
• Delete a field
• Rename a field
• Change a field's control
• Reset a field's control
• Copy a field's control
• Move field
• Tags
• Create a Tag
• Rename a Tag
• Delete a Tag

Pre-requisites && Installation

Pre-requisites

• Node LTS

Installation

npm install contentful-migration

Usage

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

Usage as a library

const { runMigration } = require('contentful-migration')
const options = {
  filePath: '<migration-file-path>',
  spaceId: '<space-id>',
  accessToken: '<access-token>'
}
runMigration(options)
  .then(() => console.log('Migration Done!'))
  .catch((e) => console.error(e))

In your migration description file, export a function that accepts the migration object as its argument. For example:

module.exports = function (migration, context) {
  const dog = migration.createContentType('dog')
  const name = dog.createField('name')
  name.type('Symbol').required(true)
}

You can also pass the function directly. For example:

const { runMigration } = require('contentful-migration')

function migrationFunction(migration, context) {
  const dog = migration.createContentType('dog')
  const name = dog.createField('name')
  name.type('Symbol').required(true)
}

const options = {
  migrationFunction,
  spaceId: '<space-id>',
  accessToken: '<access-token>'
}

runMigration(options)
  .then(() => console.log('Migration Done!'))
  .catch((e) => console.error(e))

Documentation & References

Configuration

Chaining vs Object notation

All methods described below can be used in two flavors:

1. The chained approach:

   javascript const author = migration .createContentType('author') .name('Author') .description('Author of blog posts or pages')

2. The object approach:

   javascript const author = migration.createContentType('author', { name: 'Author', description: 'Author of blog posts or pages' })

   While both approaches work, it is recommended to use the chained approach since validation errors will display context information whenever an error is detected, along with a line number. The object notation will lead the validation error to only show the line where the object is described, whereas the chained notation will show precisely where the error is located.

migration

The main interface for creating and editing content types and tags.

createContentType(id[, opts]) : ContentType

Creates a content type with provided id and returns a reference to the newly created content type.

id : string – The ID of the content type.

opts : Object – Content type definition, with the following options:

• name : string – Name of the content type.
• description : string – Description of the content type.
• displayField : string – ID of the field to use as the display field for the content type. This is referred to as the "Entry title" in