@cooperco/contentful-cli-migrations
v0.5.1
Published
Contentful CLI Migration Tool
Downloads
238
Readme
Contentful CLI Migrations
Contentful CLI Migrations is a JavaScript open-source library for automating Contentful migrations. It provides a convenient way to manage and apply migrations to your Contentful space using the command line.
Note: This is NOT the official Contentful Migration tool, but it's based on it. That can be found on GitHub 🔗 or NpmJS 🔗
✨ Features · 💡 Installation · 📟 Example · 🎹 Usage · 🐦 Write Migrations · 📅 ToDo · 👾 Contributors · 🎩 Acknowledgments · 📚 Collection · 📄 License
✨ Features
- Automated Migrations: Easily define and execute migrations to apply changes to your Contentful space.
- Command Line Interface: Use a command-line interface to run migrations and manage the migration process.
- Configuration: Define migration settings and options using a configuration file or command-line arguments.
- Environment Integration: Seamlessly integrate migrations into your development and deployment workflow.
- Version Control: Track and manage migrations using version control systems like Git.
- Extensible: Customize and extend the migration functionality to suit your specific needs.
💡 Installation
To use this helper library, you must have Node.js 🔗 and npm 🔗 installed.
To install it, simply run:
npm install contentful-cli-migrations --save
Or, if using yarn 🔗:
yarn add contentful-cli-migrations
Similarly, if you are using Bun 🔗, just run:
bun add contentful-cli-release
Requirements
node
>= 18.0.0npm
>= 9.5.0contentful-management
>= 7.50.0contentful-migration
^4.9.4- contentful-lib-helpers >= 0.3.3
Set-up
Create a
migrations/scripts/
directory in your project. This directory will contain your migration scripts.Define your migration scripts inside the
migrations/scripts/
directory. Each migration script should be as follows:- Be a separate file with a specific naming convention, such as
0001-migration.cjs
,0002-migration.cjs
, and so on. - The migration file names should contain a progressive number and a dash (
-
). In this way the script can intercept them. - We recommend using a certain amount of leading zeros to keep the migration in order inside the folder (that's why
is
0001-
and not1-
). - The folder should not contain any migration with a duplicated number (
0002
and02
will be considered duplicated). - Migration file's extension should be
.js
or.cjs
depending on the use of"type": "module"
in your package.json.
- Be a separate file with a specific naming convention, such as
In Contentful, you will need what we call a 'Counter' entry. It means that you will need to create an entry and assign one of its field to register the latest migration that has run successfully.
- You will need to take note of the entry-id;
- Then the field id. We recommend a content-type with very few fields.
- And finally the locale of that field. If unsure, you should set it up as the default Locale, usually
en-US
oren-GB
.
Note: the entry can stay in 'draft' status, since it doesn't need to be published to be used.
Set up your
.env
/.env.local
configuration file to specify the required environment and migration settings. The configuration options include:CMS_MANAGEMENT_TOKEN
: The Contentful CMA token for accessing your Contentful space.CMS_SPACE_ID
: The ID of your Contentful space.CMS_MIGRATIONS_DIR
: The path to the migrations directory in your project.CMS_MIGRATIONS_COUNTER_ID
: The ID of the entry used to store the migration counter.CMS_MIGRATIONS_COUNTER_FIELD
: The ID of the field in the counter entry that stores the actual migration counter.CMS_MIGRATIONS_COUNTER_LOCALE
: The locale used to retrieve the migration counter from the field.
You can define these options in a configuration file (e.g., .env) or pass them as command-line arguments when running the migrations.
When you start your project with contentful you usually start with an empty master
environment. We have few advices
on how to keep the migrations as clean as possible for different environments:
- Set-up in your environment your default locale (ie:
en-US
) and eventually additional locales. - If possible, duplicate immediately the empty
master
environment as a new environment (ie:empty-DO-NOT-DELETE
). This will ensure a clean environment where you could run a Contentful import or the migrations. - After that, create a content-type of type key-value for the Counter Entry. Or run the script with
--initialise
to set up the counter content-type and entry for you. - Once the Counter entry is created in the
master
environment, take note of the entry-id, field-id and locale. When duplicatingmaster
for yourdev
orstaging
environments, these values will remain the same (so you won't have to get confused with different values for different environments). - Ideally you should start creating all the Content-types using only migration scripts. Together with the empty environment, this will ensure the possibility to have a clean history of your Content-types.
📟 Example
Once everything is set up, running migrations is actually pretty simple
npx contentful-cli-migrations --to "<environment-id>"
The --to
(or --environment-id
) is the only mandatory command line option. And it tells the environment to apply the
migrations 'to'.
Since the management token would give you access to all environments, there is no default environment value in the
.env
file, forcing you to specify the target environment for 'safety' reasons (surely you don't want to run them on
master
accidentally).
🎹 Usage
This script can be used from the command line and accepts various arguments for customization:
--to
or--environment-id
[MANDATORY]: The environment id to which migrations will be executed.--space-id
: The Contentful space id.--management-token
or--mt
: The Contentful Management Token.--migrations-dir
: To specify a custom directory for the migrations (default is sub-directoryCMS_MIGRATIONS_DIR
ormigrations/scripts
in your project root). The script will exit if this custom folder doesn't exist.--initialise
: This might be needed the first time to 'override' trying to read a Content-type and an Entry that don't exist yet. If you already have your environment set up, you can just create a counter entry of one of your existing Content-types, and skip this option.--counter-id
: The ID of the entry used to store the migration counter.--counter-field
: The ID of the field in the counter entry that stores the actual migration counter. Example:title
.--counter-locale
: The locale used to retrieve the migration counter from the field. Default:en-US
--force-yes
: The script runs a migration at a time, asking you to confirm it manually (Y/N). In a CD/CI pipeline, you will need to set up--force-yes
so that all migrations will run without any request for interaction.
🐦 Write migrations
There are some guidelines and some few tricks that can be implemented when writing a Contentful migration. For more info, look at the separate documentation on How to Write Migrations.
📅 Todo
- Add Rollback migrations support.
- Add Migration Diff and automatic generator.
- Add better logging (+ colors).
- Add tests.
👾 Contributors
Contributions
Feel free to open issues or pull requests in our GitHub Repository if you have suggestions or improvements to propose.
🎩 Acknowledgements
I would like to express my gratitude to the following parties:
- Atida 🔗, the company that has allowed these scripts to be open sourced. Atida is an e-commerce platform that sells beauty and medical products. Their support for open source is greatly appreciated. A special thank to
- Shaya Pourmirza that has been a great promoter and supporter of this initiative inside the company.
- Contentful 🔗, for creating their excellent content management platform and the JavaScript CMA SDK that this
- library is built on. Without their work, this project would not be possible.
Thank you to everyone involved!
📚 Other Scripts in the same collection
We produce a bunch of interesting packages for Contentful. You might want to check them out:
- Contentful Lib Helpers (GitHub and NpmJS): Utility Library for Contentful Management API.
- Contentful CLI Export (GitHub and NpmJS): Simplifies backup of your Contentful Environment.
- Contentful CLI Migrations (GitHub and NpmJS): Tool to automate and scale Contentful Migrations.
- Contentful CLI Release (GitHub and NpmJS): Release utilities to deploy Contentful in a CI/CD.
📄 License
This project is licensed under the MIT License