migrating-to-modifier-node

Migrating to Modifier.Node — Persistent Nodes Over composed { }

Modifier.composed { } allocates a fresh composable scope per modifier per composition: it cannot be skipped, cannot be hoisted, and forces the parent to run on every recomposition. Modifier.Node is a persistent node diffed by ModifierNodeElement.equals() — created once on first apply, updated in place on subsequent applies. There is no per-recomposition allocation, no fresh composable scope, and no parent invalidation chain, which is why Android Developers describes the system as "designed from the ground up to be far more performant" than the legacy composed { } factory (see developer.android.com/develop/ui/compose/custom-modifiers). This skill teaches Claude how to author new modifiers as Modifier.Node and migrate legacy composed { } factories.

When to use this skill

• A custom modifier currently uses Modifier.composed { } (search the module for Modifier.composed).
• Authoring a new custom modifier from scratch — never start with composed { }.
• A code review surfaces a composed { } factory.
• The custom modifier needs a CoroutineScope (animation loop, debouncer), reads a CompositionLocal, participates in layout / drawing / pointer input, or tracks layout coordinates.
• A @TraceRecomposition log shows the parent composable recomposing on every frame because a composed { } modifier is in the chain.

When NOT to use this skill

• The "modifier" is actually a one-line composable wrapper that can stay a @Composable function — leave it alone.
• The built-in modifier composition (Modifier.padding(...).clickable(...)) is sufficient, no custom node behavior needed.
• The fix the developer needs is reordering an existing chain, not authoring a new node — see ../ordering-modifier-chains/SKILL.md.
• The custom modifier reads a hot animation value via Modifier.composed { } only to feed a value-form modifier underneath — the underlying issue is a wrong-phase state read; see ../../recomposition/deferring-state-reads/SKILL.md.