How to sync spaces in Contentful

Blankwaves 7 in azure
February 11, 2015



Disclaimer: The space sync tool is deprecated as of January 2017. We're working hard on providing a better and more flexible way to sync your spaces, and we'll have updates soon.

Update #3: On February 2017 we retired our space synchronization tool. Instead, we suggest following the best practices for multiple environments. Also we're in the process of baking mutliple environments directly into our product, to bypass using the CMA to propagate structure and entries between spaces.

Update #2: On February 2016 we released our new Roles and Permissions system which allows our users to setup workflows similar to the ones demonstrated on this blog post. We now discourage the use of this tool or the space synchronization tool to create these kinds of workflows and won't support these use cases on the space synchronization tool moving forward. If you have any questions regarding how to use the new Roles and Permissions features to achieve a similar workflow, please contact our support.

Update #1: On November 11, 2015, we released a new space synchronization tool, which is maintained by our own ecosystem team and supported on an ongoing basis. While the tool from our partner Xebia is still available, we highly recommend using the new version. Check out our tutorial for our new tool.

Contentful spaces workflow

While Contentful may appear simple in its structure, its flexibility lends itself to custom configurations which can enable custom workflow requirements. Today we would like to showcase such a requirement that our partner Xebia has elegantly addressed.

Xebia, a software consulting firm, uses Contentful to power a 600+ pages website of a major French online bank. Part of this project was to set up two independent environments: one for production and one for content testing, where editors would work and preview the material. Naturally, these environments need to be in sync, so that all the changes and updates would be copied to production automatically. Below is the story of how we have accomplished that.

Spaces inside Contentful are independent entities, so we have created two spaces: editing and production. Editors work only in the editing space and never touch production. The sync is done with a Node.js script which uses the Contentful APIs to fetch the data from one space and copy it to the other. The script is available in our ecosystem area.


The script syncs content from the source space to the destination space using the Contentful Sync API. When launched for the first time, the script simply copies everything from the one space to the other. When the script is run for the second time and onwards, it copies only new and updated content. This is achieved by writing the synchronization token to a file which would be checked when the script is executed the next time.

How to start syncing spaces in Contentful

First, create a configuration file – config.json. It should define the spaces IDs, the Contentful API tokens and sync token filename. Here is an example:

Running the script requires an installation of Node.js. First, get the script:

Then run it, specifying where the configuration file is:

By default the script syncs both the content model and content entries. You can choose to sync only model or only content with the -t flag: -t model or -t content, respectively.

Hopefully, this script will save you some time in case you have a similar setup. Make sure that your editors are happy, and please let us know about any problems or feature requests.

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