skill by
@expoFramework (OSS). Migrate an existing Apple/Swift Expo native module from the Expo Modules API 1.0 definition DSL to the 2.0 macro API (sometimes called v2) while preserving its JavaScript and TypeScript contract. Use when converting or incrementally adopting @ExpoModule, @JS, @Event, @SharedObject, or @Record in an existing module. Do not use for creating a new module, general Expo SDK upgrades, or Android/Kotlin migrations.
Permissions
Files
Framework (OSS). Migrate an existing Apple/Swift Expo native module from the Expo Modules API 1.0 definition DSL to the 2.0 macro API (sometimes called v2) while preserving its JavaScript and TypeScript contract. Use when converting or incrementally adopting @ExpoModule, @JS, @Event, @SharedObject, or @Record in an existing module. Do not use for creating a new module, general Expo SDK upgrades, or Android/Kotlin migrations.
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.
Install
It’s free, and every skill you add syncs into every AI tool on your computer, instantly.
Version history
The Expo Modules API 2.0 macros require expo 57.0.7 or newer. 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; do not attempt the migration against an unsupported version. 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.
references/migration-map.md before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.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.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 an SDK number.Inspect repository instructions and the worktree before editing. Locate the Swift module classes, records, shared objects, native views, JS/TS bindings, tests, example app, podspec, and installed or checked-out expo-modules-core.
Inventory every exported item before rewriting it:
Use the TypeScript declarations and JS call sites to resolve ambiguity. Do not silently "improve" requiredness, rename an event, or change sync behavior during a syntax migration.
Inspect the macro declarations and matching core hooks in the dependency actually used by the target. Do not assume that all items in the 2.0 design are present because one macro compiles.
Classify each 1.0 item as:
Prefer an incremental mixed-mode result over speculative generated code. Keep definition() for any remaining DSL elements; delete it only when it is empty and the resolved module name is preserved by @ExpoModule.
Migrate one semantic group at a time: module naming, functions, properties/constants, events, shared objects, then records. Keep the diff narrow.
Follow these invariants:
references/migration-map.md..d.ts files unless the user requested an API change.After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.
When step 2 classified an item as Blocked, or a migrated group fails to build or breaks the contract, do not force it. Stop on that group and:
Ask the user how to proceed for that item, with two options:
definition() DSL alongside the migrated @ExpoModule (mixed mode) and continue with the other groups.Default to co-existence when mixed mode is verified safe, since it preserves the most progress. Revert when the half-applied change left the module in a non-building state and cannot be salvaged incrementally.
Open a tracking issue on expo/expo noting the functionality that 2.0 does not yet cover, so the gap is recorded rather than silently worked around. Use gh issue create --repo expo/expo and confirm with the user before posting (per repo conventions, do not post outward-facing comments without approval). Include:
references/compatibility.md)expo-modules-core version/branch checked outReference the issue in the handoff so the remaining DSL entry is traceable to a known limitation.
Keep going with the groups that do migrate cleanly; one blocked member does not block the rest.
Run the narrowest available checks first, then the real integration surface:
expo-modules-core.Name, migrated Function/Property/Constant/Events entries, old sendEvent calls, @Field, and duplicate registrations.Expansion tests alone are insufficient: generated macro code can look correct while failing against mismatched core symbols. If dependencies changed or macro plugin flags are missing, reinstall JS dependencies as appropriate, run the repository's CocoaPods installation workflow, and restart Xcode before diagnosing plugin communication failures.
Report:
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-migrate-module" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.
In these kits
Works with
Claude, Codex, Cursor & more