Managing Contentful Migration Scripts with Multiple Environments

The Problem

If you are building a website and using Contentful, then you might have experienced the benefits with using a headless CMS that also has robust API functionality. Using Contentful allows developers to build out a Content Type structure which allows content owner to easily create reusable content that can be added to different site pages.

Contentful recommends using the Contentful Migration Tool along with the Contentful CLI as best practice when your project is using more than one environment in your Contentful Space (i.e. when your Contentful Space has a development and a master environment). However, as great as the Contentful Migration Tool is, my team and I became easily frustrated as the project grew and multiple change request came our way. Lets say a migration script was created and successfully ran on both environments, now you have on your development and master environment (in your Contentful space) a Content Type named Article. Article has the following fields; Title, Author and Date Published.

Let’s say their is a change request to update the field name Title to Article Title along with adding a new field called Ratings. When using the Contentful Migration Tool you would not be able to use the same migration script that was used to create the Article Content Type without doing some modifications to it. You would have to, first, replace createContentType with editContentType methods. Second, remove the fields that are applicable and third, add the new field. See example below.

Diving Deeper

With the example above, notice that you will have to call createContentType instead of editContentType and editField instead of createField to successfully update the field with new options. If these changes are not made, the script will not run successfully and you will get an error from Contentful Migration Script stating that you cannot create a field or content type that already exist. A few pain points to recap here are; the scripts are not completely reusable and the scripts are not DRY.

The Solution

The birth of Contentful Smart Migration(CSM). This NPM package adds an abstraction layer over the Contentful Migration Tool which reduces the pain points mentioned. Using the same use case scenario, thanks to CSM we only need one script without explicitly using createContentType , editContentType , createField , editField .

Now lets modify the Content Type that will satisfy the request to change the field’s name from Title to Article Title and add a new field with the name Ratings.

With CSM, there is one script to rule them all (for building Content Types).

The breakdown

Install the package

Requiring the CSM methods

Wrap the script in Contentful’s migration function and pass in the two arguments (required).

module.exports = async function(migration, context) {}

The migration object is the main interface for creating and editing content types. The context object provides the Contentful API features not supported by the migration object. Read more here.

Creating the Content Type

Creating fields

By default fields are type Symbol and set to required: true, localized: false, disabled: false, omitted: false, deleted: false , validations: [].

Create a new instance of OperateOn. Pass the migration , context , and article objects along with the fields array as it’s arguments.

The migration object being passed gives CSM access to Contentful’s migration methods, which are used to create or edit your Content Types and its respective fields.

The context object gives CSM the ability to query search for the respective content type to see if already exist.

The article object provides the information about the Content Type.

The fields array are the Content Type’s fields that will be created or edited if applicable.

Finally, calling the methods

Want to know more of what CSM can do? Read these docs.

Husband, Father, Web Dev and many other things.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store