# Expo Migrate Module

Migrate an existing Apple/Swift Expo native module from the Expo Modules API 1.0...

- Repository: https://github.com/expo/skills (4005 stars)
- Category: Mobile
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add expo/skills --skill expo-migrate-module -g -a claude-code -y`
Codex: `npx skills add expo/skills --skill expo-migrate-module -g -a codex -y`
Cursor: `npx skills add expo/skills --skill expo-migrate-module -g -a cursor -y`
Gemini CLI: `npx skills add expo/skills --skill expo-migrate-module -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add expo/skills`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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` `58.0.21` or newer. Earlier `58.0.x` releases lack tuple conversion and the `swift:check` and `swift:expand` commands of `expo-modules-cli`. Older ones also lack `lazy` `@JS` properties, `SharedRef<T>` subclasses in `@SharedObject`, static shared-object members, and `.withAsync`, and the oldest lack closure arguments and free-form `Any` return values. SDK 57 also lacks `.concurrent`, `@Union`, and module auto-discovery. Do not target either. Before editing, check the installed version (`npm ls expo`, or the lockfile). If it is older, stop and tell the user to upgrade first.

Check the example app's own dependencies 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 macro and core surface changed in almost every `58.0.x` patch release, so step 2 must still verify the installed source.

The macros are still **experimental and undocumented**: SDK 58 has no page about them in the Expo docs, and 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

The rest: https://github.com/expo/skills/blob/HEAD/plugins/expo-experiments/skills/expo-migrate-module/SKILL.md