comfy-custom-nodes-migration

Migration fallback

A module loads through exactly one registration route and NODE_CLASS_MAPPINGS wins: when present and not None, loading stops there and a comfy_entrypoint in the same module is never called. An empty mapping still wins; only absent or None falls through. A half-migrated module therefore presents as "the new nodes did not appear", with no error. Migrate a module whole, or keep the two generations in separate packs.

Changing a node id breaks every saved workflow that used it, so migrate identity explicitly rather than renaming.

Deprecating and replacing are two stages, not one recipe. is_deprecated marks a node that is still registered, steering new users away while old workflows keep running. A replacement takes over only once that class stops being registered. Deprecate first, register the replacement in the same release, and let the release that finally drops the old class carry the migration.

Build io.NodeReplace(new_node_id=…, old_node_id=…, old_widget_ids=…, input_mapping=…, output_mapping=…) and await node_replacement.register(...). It fires only when the old class is absent from the loaded catalog; only the first replacement registered for an old id is used; unmapped inputs are dropped and widget values match positionally, which is what old_widget_ids orders; and moving a downstream link to a different output position needs an output_mapping entry. A runtime that does not expose node_replacement has no replacement path — state that limit rather than working around it.