create `@xstate/codemods` package and `v4-to-v5` migration codemod

[with-heart]

This PR resolves #321 by creating the @xstate/codemods package and implementing TypeScript transformers for each of the v4-to-v5 changes.

This is currently just a draft as we figure out the ideal way to implement the codemod and handle all of the necessary changes.

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 5fa384ee0df30b58b5d39bc359c86bb158cda5df

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[with-heart]

The initial impl for machine-to-create-machine is super naive. We're traversing for each node in the tree that needs to be renamed and renaming it, which works but it's a lot of effort compared to what we could do with the ts language server or ts-morph. Going to investigate those alternatives next I think

[tivac]

Any further progress planned for this? We're hoping to try out v5 soon but have enough machines that manually porting them all is gonna be pretty time-consuming.

[Andarist]

I'd recommend using XState v4 and v5 side by side and migrating to v5 gradually. You want to make sure that the behavior of your system stays unaffected and that the codemod can only migrate some syntax-oriented things, like renaming cond to guard.

To use both you can add such dependencies:

"@xstate/react5": "npm:@xstate/[email protected]",
"xstate5": "npm:[email protected]",

And if you need an integration package like @xsttae/react (or some other) then you need to link it with the correct XState version after you install the packages. You can do this with a script like:

const fs = require('fs-extra');
const path = require('path');

const rootNodeModules = path.join(__dirname, '..', 'node_modules');

fs.ensureSymlinkSync(
  path.join(rootNodeModules, 'xstate5'),
  path.join(rootNodeModules, '@xstate', 'react5', 'node_modules', 'xstate'),
);

[davidkpiano]

Added this to the docs: https://stately.ai/docs/migration#how-can-i-use-both-xstate-v4-and-v5

[leggomuhgreggo]

Oh wow! This is neat. Any plans to revive this?

[davidkpiano]

Oh wow! This is neat. Any plans to revive this?

I hope to! I've been thinking about this recently - either lint rules and/or a codemod for v5 and future XState versions.

[tivac]

Reviving this would be huge for me, the guy who still has a ton of v4 statecharts with no straightforward way to move to v5 without a huge amount of manual work.

[with-heart]

I'm working on an rfc for codemods so we can have a solid plan ❤️