README.md

cf-migrations

cf-migrations is a tool for deploying and managing migrations and environment aliases in Contentful.

⚙️ Installation

Pre-requisites:

• Node LTS

npm install --save cf-migrations

🔌 Usage

🔐 Contentful credentials

Almost all the cf-migrations commands require contentful credentials besides specific arguments per command. You can pass those arguments as command line arguments or environment variables.

You can use the -h or --help in any command to show its usage help. For example, run npx cf-migrations init -h to see the required and optional arguments of the init command.

💡 cf-migrations uses dotenv to read a .env file so you write your credentials only once when using cf-migrations in your project locally.

🥾 Init environment

In order for you to use cf-migrations deploy or release commands, you should run the following:

npx cf-migrations init

It creates a new content model named cf-migrations that will store every deployed migration file name. cf-migrations uses these names to assess if there're pending migrations yet to be deployed.

🏗 Create migration

After initializing your contentful environment, it's time to write some migrations! To create a new migration file in your project, type the following:

npx cf-migrations create create-foo --migrationsDir src/migrations

It will create a typescript migration file, src/migrations/1660225580514-create-foo.ts for example. Use the flag --useJavascript or --js to create a javascript file instead.

Note that the migrations should have a proper timestamp.

🚚 Deploy migration

After writing your migration, you can deploy a single or every pending migration with the following command:

npx cf-migrations deploy

📢 Note that the "deploy" and "release" commands only support javascript files. See the typescript section for more details about how you could work with typescript migrations.

After the deployment, the pending migrations changes will be applied and their file names will be added to the cf-migrations content type.

🚀 Release new environment version

The release functionality works by assessing if there are pending migrations to be deployed (this verification can be skipped), creating a new environment, deploying pending migrations on it and update the target environment alias to the new environment.

npx cf-migrations release

Since the number of available environments is limited, the oldest release that is not aliased will be removed.

📢 Since contentful does not have a functionality yet to also copy the scheduled actions if you create a new environment from an existing one, we have created a feature as a workaround to do the job. The feature is by default activated and can be deactivated by setting the parameter copy-scheduled-actions to false.

📚 API

Using cf-migrations' CLI isn't the only option: you can integrate its functionalities with your project by using the library's API.

The API documentation can be found here.

🎖 Typescript support

You can use typescript to write the migrations but you'll need to use tools such as ts-node or have compiling tooling for your migrations.

Suppose you have the following project where there is a typescript compilation tooling:

./
├── my_project/
│   ├── tsconfig.json
│   ├── src/
│       ├── migrations/
│           ├── 1660225580514-create-contenty-type.ts
│           ├── 1660225721863-add-field.ts
            ...
│   ├── dist/
│       ├── migrations/
│           ├── 1660225580514-create-contenty-type.js
│           ├── 1660225721863-add-field.js
            ...
...

You could deploy the migrations with the following command:

npx cf-migrations deploy --migrationsDir dist/migrations

An alternative is to run the deployment with ts-node, therefore no need to compile the migrations:

npx ts-node node_modules/.bin/cf-migrations deploy --migrationsDir src/migrations

👥 Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

🏛 License

MIT