Become a Contentful migration expert with the Migrations CLI

Building a successful digital product requires multiple prototypes, design iterations, and business pivots to arrive at a stage where users enjoy using the product. Keeping content and code changes in sync is one particularly thorny problem that crops up in this context. Unfortunately, this reality of building modern software is poorly accommodated by the traditional CMS, making it a tool that developers love to hate.

We wanted to learn from these mistakes and ensure that Contentful is easy to use not only during the inception phase, but also once projects mature and evolve. This is where content migration tooling comes to the rescue.

To developers, Contentful’s appeal lies in the fact that it adapts to custom content requirements and easily integrates into any technology stack. Today, we’re releasing an updated version of our content migration tooling—a command-line interface (CLI) library that will help development teams programmatically iterate their content. The Migration CLI, available as a Github repo and npm package, enables developers to apply content type changes and entry transformations at scale.

There are many use cases that benefit from this functionality. Let's imagine for a second that you are running an e-commerce website with a blog, a regular expert column, and landing pages with seasonal recommendations. Here are some changes you might apply to your website:

  • Change a field with a description of an item from short text to long text type

  • Split a field called "Full name" into separate "First name" and "Last name" fields

  • Update the blog to display "Author" pages and ensure that individual posts link to these pages

  • Add categories to the expert column and assign a relevant category to published entries

  • Update all existing entries to include the correct URL to assets served from a new domain

  • Deprecate the field "promotional item" in the merchandise content type

The migration tooling helps you to execute all of these changes programmatically, and it allows you to do that all at once or one step at a time.

At its core, the Migration CLI lets you create and update content types; add, update, remove, and change the order of fields; transform entries and add link references to your entries. It comes with robust validations, providing informative error messages in cases where migrations fail. It's important to note that the Migrations CLI does not replace, but rather complements, the export and import tooling. If you need to move content from one space to another, those are still the right tools to use.

The release of content migrations aligns Contentful more tightly with the development tools and agile practices embraced by modern engineering teams. We have seen many of our beta customers use the Migration CLI to automate content updates and make Contentful a part of their continuous delivery process.

"Having a well-defined source of truth for our content models allows us to make a copy of the live content and test how it’s impacted by the latest code changes in non-critical spaces."
— Jody Zeitler, a software engineer at RedBrick Health.

To help you get started with content migrations, we have put together a detailed guide and a video overview. If you are new to content workflows or would like to get more general perspective on the topic, we encourage you to read the CMS as Code article we published a year ago. And in case you would like to help us improve the Migrations CLI, submit a pull request on Github.

About the author

Don't miss the latest

Get updates in your inbox
Discover how to build better digital experiences with Contentful.
add-circle arrow-right remove style-two-pin-marker subtract-circle remove