ng update @my/lib - What's the order of executing custom Angular schematics? 🤹

Custom Angular update schematics are executed in the alphabetical order by their names declared in migrations.json.

When maintaining a custom Angular library and making breaking changes in major version, you'd like to provide your library users with a smooth migration path (nobody likes to spend much time fixing problems after upgrading npm dependencies, right?). For that purpose you can leverage scripts (aka. Angular custom schematics) that will apply code modifications to fix the breaking changes directly in user's codebase - when running a command, i.e. ng update @my/lib@2.0.0.

All the migration scripts of schematics are declared in a json file, i.e. migrations.json. And each of them is assigned to specific version (so you can have different schematics for migration from 1.x to 2.0, and different from 2.x to 3.0).

But you might have multiple schematics targeted for the same version, i.e. 2.0.0. In case the order of schematics matter, you need to be aware that they are executed always in the alphabetical order by the name. That's why we should care about the prefix convention in migrations.json declared in our lib, for example numbering -01-, -02-, ...:

{
  "schematics": {
    "migration-v2--01-components": {
      "version": "2.0.0",
      "factory": "./2/component-migration#migrate",
      "description": "Migrate components"
    },
    "migration-v2--02-services": {
      "version": "2.0.0",
      "factory": "./2/services-migration#migrate",
      "description": "Migrate services"
    },
  }
}

To proof it's not the order of keys in the JSON that determines the order, but the alphabetical order of the keys (migration-v2--01-components, migration-v2--02-services), see the GitHub @angular/cli source code - sorting schematics by name.