ng update @my/lib@version - Which migration schematics will be executed? 🤷

The command ng update @my/lib@version downloads the specified version of the library and launches all schematics listed in its migrations.json that have an appropriate property of "version" within the semver range from >installedVersion to <=targetVersion.

Example

For instance, consider the following conditions:

• The locally installed version of @my/lib in my project is 1.1.0.
• The latest published npm version of @my/lib is 4.8.9.
• Now, when we run ng update @my/lib (or ...@my/lib@4 or ...@my/lib@4.8 or ...@my/lib@4.8.9, it doesn't matter),
• and the file migration.json of @my/lib contains migrations for the "version" 2.0.0 and 4.5.0:

{
  "schematics": {
    "migration-v2": {
      "version": "2.0.0",
      "factory": "./migration-v2#migrate",
      "description": "Migration for v2.0.0"
    },
    "migration-v4.5": {
      "version": "4.5.0",
      "factory": "./migration-v4_5#migrate",
      "description": "Migration for v4.5.0"
    },
  }
}

...then the following migrations will be executed, in ascending order of version:

• Migration for v2.0.0
• Migration for v4.5.0

This is because they fall between the currently installed version (>1.1.0) and the target version (<=4.8.9).

Note: If we were to run ng update @my/lib@ with the target version lower than 4.5.0, for example, ng update @my/lib@3, only the following migration would be executed:

• Migration for v2.0.0

However, the Migration for v4.5.0 would not run.

Angular CLI source code analysis

Here's a proof in the source code of the Angular CLI:

• If the "version" field from migrations.json belongs to the appropriate semver range, then this migration is launched (see source).

• The appropriate semver range means something between >fromVersion and <=toVersion (see sources: executeMigration() and invocation of executeMigration()).

• The fromVersion and toVersion respectively mean: installed.version and target.version (see source).

Therefore, all migrations between >installed.version and <=target.version are launched.

Comments

[Neil Deighan]

Hi there doesn't seem to be a lot of documentation around for custom ng-update implementation, and those I have found, I have managed to cobble together, however.

1) I have got the ng-add to work fine
2) I have got the ng update @myscope/mylib to work, i.e. just updates the package only

but .. I can only get migrations to work if I do this ..

ng update @myscope/mylib --migrate-only --from x.xx (and also adding --to x.xx)

so the above picks the correct schematics based on version in my migrations.json and runs them fine, so the setup must be ok

I thought by running

ng update @myscope/[e-mail]

would both update package and then run migrations automatically after, is this stil the case or has something changed ? Am i missing something ?

thanks for any insight you may have

[Krzysztof Platis]

I thought by running
ng update @myscope/[e-mail]
would both update package and then run migrations automatically after

That's exactly what I'd expect too! 🤔

[Neil Deighan]

Strange eh? must be missing something ? .. but update package works fine, and using --migrate-only runs the correct versioned migration schematics .. just not one after the other in one-liner ... not sure where to look, as doing the --migrate-only was part of my "debugging" ... I am using v18 angular, I know there been a few changes, but cant see trawling through their code

[Krzysztof Platis]

For debugging Angular CLI internal code, try runninng your ng update... inside VSCode Javascript Debugging Terminal. But before doing it, add breakpoints in your VSCode (add red dots at a margin near line numbers, by clicking) in JS files inside the foleder /node_modules/@angular/cli/src/commands/update/..., e.g. in its files .../cli.js and .../schematic/index.js.
Please mind hovering variables with mouse, to inspect their values, when runtime stops on your breakpoint. I hope this way you'll be able to find out the root cause of the problem.

I'd put breakpoints the following places and go line-by-line, when debugger stops on those breakpoints after running your ng update... inside the VSCode Javascript Debugging Terminal:

Note: After running your ng update... inside the VSCode Javascript Debugging Terminal, you should see the Debugger panel (shown in the picture below) in VSCode, which will allow you to debug similarly like in Chrome Dev Tools, e.g. step over a line, step into the current fucntion, step outside the current function:

[Neil Deighan]

Will have a go at this in a bit, thanks