How to - Debugging and Executing Local Migration Generators

[LongLiveCHIEF]

I can't access Slack, so hoping the discussions board is monitored.

I need to make changes to over 70+ projects, adding a few config files related to new configurations I'm adding to an existing target.

This is my first experience with local generators, and the concept seems pretty well formed out, but I think there's a bit of a gap in documentation around the best way to go about modifying existing projects at this scale.

It seems like the best approach is a migration from what I can tell, since it gets a tree as an arg. There are a few things I can't figure out, but have taken some informed guesses based on strategies I've seen in packages for generators in this repo.

If I get help answering these questions, I'd be more than happy to contribute documentation PR's to the cause.

Most of these questions are predicated on the assumption that a migration really is the best way to modify existing projects. If this is not a correct assumption, then I'd still like the answers so I can contribute doc improvements (and a suggestion on the best approach for this scenario).

1. How do I debug a migration? I can do local debugging in vscode of a normal generator, since it has a cli execution command of nx g [generator], but I can't find a way to execute migrations in a similar way.

2. Is the tree that gets passed to the default function for the migration filtered in any way? The big question here is if there's something that looks at each project to determine if the plugin I'm creating a migration for is used.

3. Is there a recommended approach for executing local migrations? Right now the best I can figure is to increment the package version of the plugin after specifying a version for the migration. The docs state that the migration will run when upgrading beyond the indicated --packageVersion number supplied, which makes sense for a plugin that isn't local, but becomes less clear when thinking of running local migrations. I've noticed in many of your packages you'll use the approach of using X.Y.Z-beta.0, and I'm assuming that's how you get a migration to run from a local generator for a matching version number. (this is also what caused me to think the best approach for project config updates from a local generator is a migration)

New codemod feature?

Would it make sense to add a nx codemod or nx mod cli, with an accompanying nx generate @nrwl/nx-plugin:codemod command? This is something I'd be happy to take a look at, as it would seem to make some of the process above a bit cleaner and more sensible.

[LongLiveCHIEF]

So far, locally I've figured trying to run nx migrate my-plugin in a javascript debug terminal in vscode is the debugging approach, but haven't quite gotten things to work.

[jasonmacdonald]

I know this is an old discussion but were you able to answer these questions? I'm in exactly the same boat and it's not clear how to run these things effectively during development of the migration. Do you have to constantly change the version number each time to test?

[LongLiveCHIEF]

Iirc I created a generator that made the changes. I think this was even at the advice of an NX team dev. I think it was something about how migrate works and needing published packages, but that essentially migrate was a generator anyways.

Since the local plugins were local to begin with, it made much more sense to use a generator and then check in the changed local plugins code.

[jasonmacdonald]

Ah, that makes sense. Thanks very much for replying and so quickly. You may have just saved me hours of pulling my hair out lol.