Adding CAMO to an existing project using Typescript migration files

Install CAMO

Navigate to your project directory. We'll assume that you have Typescript already installed. This guide assumes that you are using at least Node v16.

We'll be setting up a seperate tsconfig.json file that references @tsconfig/node16 just for migration file compilation.

# npm
$ npm install --save-dev @sambauers/camo @tsconfig/node16

# or yarn
$ yarn add --dev @sambauers/camo @tsconfig/node16

# or pnpm
$ pnpm add --save-dev @sambauers/camo typescript @types/node @tsconfig/node16

Add a migrate script to your root package.json

In your projects root package.json add this script in the scripts definitions. Adjust the migrate script to call your preferred package manager (npm shown):

{
  "scripts": {
    "migrate:build": "rm -rf migrations/.build && tsc --project migrations",
    "migrate": "npm run migrate:build && camo"
  }
}

Create a source migrations directory

This will contain the Typescript migrations.

$ mkdir -p migrations/src

Create the Typescript configuration

Add a file in the new migrations directory named tsconfig.json containing:

{
  "extends": "@tsconfig/node16/tsconfig.json",
  "include": [
    "src/*.ts"
  ],
  "compilerOptions": {
    "outDir": ".build"
  }
}

In addition to the above, if your project is written using ESM then you may need to create a package.json file in the migrations directory, containing:

{
  "name": "camo-migrations",
  "description": "This package.json file is just here to turn off ESM for the CAMO migrations.",
  "type": "commonjs"
}

This workaround will avoid errors when attempting to apply the migrations. You don't need to do this if your main project package.json is using CommonJS.

Setup the required environment variables

Create a .env file in the project root containing (at least):

# Contentful Active Migration Organiser (CAMO)
# The space ID to connect to
CONTENTFUL_MIGRATION_SPACE_ID='<your-contentful-space-id>'

# The access token to connect with
CONTENTFUL_MIGRATION_ACCESS_TOKEN='<your-contentful-access-token>'

# The local directory containing Contentful migration scripts
CONTENTFUL_MIGRATION_LOCAL_DIRECTORY='./migrations/.build'

Now when you run tsc --project migrations on the command line, or npm migrate:build to compile the migrations, it will:

• Look in migrations/src for the source migration scripts
• Compile those migration scripts
• Output the compiled Javascript files to the migrations/.build directory

Create the Contentful migrations content type

Run the migrate --list command:

# npm
$ npm run migrate --list

# or yarn
$ yarn migrate --list

# or pnpm
$ pnpm migrate --list

You will be asked if you want CAMO create the content type in Contentful.

Create a local migration file

Create a Typescript migration file in the migrations/src folder with your desired schema.

List the compiled local migration file

The compiled Javascript version of the file you created above should now be visible with the --list option:

# npm
$ npm run migrate --list

# or yarn
$ yarn migrate --list

# or pnpm
$ pnpm migrate --list

Apply the compiled local migration file

The compiled Javascript version of the file you created above should now be applied when running CAMO:

# npm
$ npm run migrate

# or yarn
$ yarn migrate

# or pnpm
$ pnpm migrate