expo-migrate-module

SKILL.md

Migrate an Expo Module

Migrate the Swift side of an existing Expo module without changing its observable JS API. Treat the current JS/TypeScript surface and tests as the compatibility contract. Leave Kotlin on the 1.0 DSL unless the user explicitly expands the task.

Prerequisite

Use expo 57.0.21 or newer. Earlier 57.x versions can compile the macros but lack many of the 2.0 features and performance optimizations, so do not target them. Before editing, check the target's installed version (expo in package.json/lockfile, or npm ls expo). If it is older, stop and tell the user to upgrade first.

Check the example app's own package.json too, not only the module root. The example app is the integration surface you build and launch in step 4, so it needs the same floor.

This is a floor, not a guarantee: the exact macro and core surface still varies within 57.x, so step 2 must still verify the checked-out source.

SDK 57 ships the macros as experimental and undocumented, with the official beta in SDK 58. The API can still change under you. Say this to the user before a large migration, and prefer incremental mixed mode over converting a module wholesale.

References

Read references/migration-map.md before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.

Read references/example.md for a full before/after walkthrough of one module through mixed mode to a complete migration. Consult it when you need to see how the per-member rules compose.

Read references/compatibility.md when the checked-out expo-modules-core version or branch is not known to support every requested macro. It explains how to verify the actual compile-time and runtime surface instead of guessing from a version number, and lists what the macros plugin gained through 0.10.0.