expo-migrate-module

Migrate Swift Expo native modules from the 1.0 definition DSL to the 2.0 macro API.

Updated Sep 6, 2026
One-click install
npx skills add https://github.com/sombek/fitness-guidance-app --skill expo-migrate-module-sombek
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: expo-migrate-module
Source: https://github.com/sombek/fitness-guidance-app/tree/main/mobile/.agents/skills/expo-migrate-module
Command: npx skills add https://github.com/sombek/fitness-guidance-app --skill expo-migrate-module-sombek

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Migrating an existing Apple/Swift Expo native module from the Expo Modules API 1.0 definition DSL to the 2.0 macro API is error-prone: macro defaults can silently rename events, change record requiredness, or move blocking work onto the JS thread. This Skill performs the migration incrementally while preserving the module's existing JavaScript and TypeScript contract. ## Core Features & Use Cases - Contract-first migration: Inventories every exported member (functions, properties, constants, events, records, shared objects, lifecycle hooks) and treats the current JS/TS surface as the compatibility contract. - Verified 2.0 surface: Checks the checked-out expo-modules-core and macro declarations before migrating, classifying each member as Migrate, Keep in DSL, or Blocked instead of assuming SDK-version support. - Safe mixed mode: Supports incremental migration where @ExpoModule coexists with a non-empty definition() for unsupported members, with guidance to open tracking issues on expo/expo for gaps. - Use Case: Convert a Swift module using Name, Function, AsyncFunction, Property, Constant, Events, and OnStartObserving into @ExpoModule, @JS, @Event, and @Record equivalents, then verify with builds, native tests, and the example app. ## Quick Start Use the expo-migrate-module skill to migrate this Expo module's Swift implementation from the 1.0 definition DSL to the 2.0 macro API without changing its JavaScript contract.

Frequently Asked Questions about expo-migrate-module

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate an Expo native module from the 1.0 DSL to the 2.0 macro API?

Inventory every exported member and its JS contract, verify the checked-out expo-modules-core supports each macro, then migrate one semantic group at a time: naming, functions, properties, events, shared objects, records. Keep unsupported members in the 1.0 definition() using mixed mode.

What Expo version is required for the Modules API 2.0 macros?

The 2.0 macros require expo 57.0.7 or newer. Check the installed version in package.json or with npm ls expo before editing, and still verify the checked-out source because the macro surface varies within 57.x releases.

Can @ExpoModule coexist with the 1.0 definition() DSL?

Yes, mixed mode is supported when the paired core merges both surfaces. Keep only unsupported entries like views, queue-pinned functions, or shared-object static functions in definition(), and avoid duplicate names across macro and DSL registrations.

Why does my migrated event name change from onProgress to progress?

The default @Event wire name strips a leading "on" and decapitalizes the remainder, so Swift onProgress emits progress. Pass the original wire name explicitly, such as @Event("onProgress"), to preserve the existing JS listener contract.

When should I not migrate an AsyncFunction to a 2.0 async method?

Do not migrate queue-pinned or blocking functions as-is, because 2.0 async members start on the JS actor. Restructure with Swift Concurrency or dispatch to the original queue inside a checked continuation, or keep the function in the 1.0 DSL.

Does this migration cover Android Kotlin modules or new module creation?

No. The migration covers only the Swift side of existing modules; Kotlin stays on the 1.0 DSL unless explicitly requested. It is not intended for creating new modules or general Expo SDK upgrades.