AutoGineer
Generated banner for Expo Migrate Module
Generated logo for Expo Migrate Module

Expo Migrate Module

ExpoOfficialPublished by Expo

  • Skill
  • Workflow
  • Software development
  • MIT
  • Low risk
Download ZIP

From the author

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.
— the description by Expo

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a systematic workflow for updating Apple/Swift Expo native modules from the legacy Expo Modules API 1.0 definition DSL to the modern 2.0 macro-based API. It emphasizes preserving the existing JavaScript and TypeScript contract, ensuring that native-side changes do not break the module's observable behavior. The process involves inventorying the current API, verifying the availability of 2.0 macro support in the target environment, and performing an incremental migration using mixed-mode development where necessary.

What it does

  • Inventories existing module exports, including functions, properties, events, and records.
  • Verifies the compatibility of 2.0 macros with the installed Expo SDK version.
  • Guides the migration of Swift code to @ExpoModule, @JS, @Event, and @Record macros.
  • Supports incremental migration through mixed-mode, keeping unsupported members in the 1.0 DSL.
  • Ensures threading and async behavior remain consistent with the original 1.0 implementation.
  • Provides a verification workflow using native unit tests and the example app.

When to use it

  • When you need to modernize an existing Apple/Swift Expo module to the 2.0 macro API.
  • When you want to adopt @ExpoModule, @JS, @Event, or @Record in a legacy module.
  • When you need to perform an incremental migration while keeping the module functional.
  • When you need to ensure that native-side changes do not alter the existing JS/TS API contract.

Advantages

  • Preserves the existing JS/TS contract, preventing breaking changes for consumers.
  • Allows for safe, incremental migration via mixed-mode development.
  • Provides clear guidance on handling threading and async behavior during migration.
  • Includes a robust verification process to ensure runtime compatibility.

Usage examples

“Migrate my existing Swift module 'CameraModule' from 1.0 DSL to 2.0 macros.”
The agent will inventory the current 'CameraModule' exports, check the installed Expo SDK version for macro support, and begin an incremental migration of the Swift classes while maintaining the existing JS interface.
“How do I handle a blocking function during my Expo module migration?”
The agent will advise on whether to keep the function in the 1.0 DSL or refactor it to use @JS(.concurrent) or other async patterns to ensure it does not block the JS thread.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/expo/expo-migrate-module/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip expo-migrate-module.zip -d .agents/skills

Documentation by Expo

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

  • 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, gives the SDK 58 status of each capability, and shows how to run the module scanners and the expo-modules-cli checks.

Workflow

1. Establish the contract

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, expo-module.config.json, and installed or checked-out expo-modules-core.

Inventory every exported item before rewriting it:

  • module and shared-object JS names

  • function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue/thread semantics (note which AsyncFunction bodies do blocking or long-running work, any .runOnQueue(...), and sync/async pairs that share a body, such as readSync and read)

  • property names, mutability, and constant caching behavior

  • event wire names and payload shapes, including events sent with no body (1.0 sendEvent("name") sends {})

  • record field names, defaults, requiredness, and nullability

  • shared-object constructors and instance/static placement (Function vs StaticFunction/StaticAsyncFunction)

  • lifecycle hooks and views

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.

2. Verify the available 2.0 surface

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:

  • Migrate: both its macro and required core runtime support exist.

  • Keep in DSL: mixed mode preserves it safely, or 2.0 lacks an equivalent.

  • Blocked: migration would alter the JS contract or requires unavailable runtime support.

A DSL member that takes or returns JavaScriptValue does not compile on SDK 58, so it cannot stay in the DSL. Migrate it to @JS with a borrowing JavaScriptValue parameter, as described in references/migration-map.md.

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.

3. Apply the migration

Migrate one semantic group at a time: module naming, functions, properties/constants, events, shared objects, then records. Keep the diff narrow.

Follow these invariants:

  • Preserve every existing JS-visible name explicitly when Swift naming rules or macro defaults differ.

  • Keep original optional/default behavior. An optional 1.0 record field must not become required merely because 2.0 can express required fields.

  • Keep same-JS-name overloads on the DSL. The plugin does not dispatch overloads, and it reports two @JS members with one JS name on one object as a build error.

  • Preserve async threading behavior. A 1.0 AsyncFunction body ran off the JS thread; a 2.0 async @JS member starts on it and leaves only at the first await. A body that never awaits therefore blocks the JS thread, with no change to the JS signature. Audit what runs before the first await, and never leave blocking I/O on the JS actor. Fix with @JS(.concurrent), return a Task.detached from a synchronous function, or restructure onto Swift Concurrency or a continuation. A plain Task { } in a @JS function that is not nonisolated starts on the JS thread, so it does not help. Queue-pinned functions get the same treatment; .runOnQueue(.main) becomes a @MainActor async function. Merge a sync/async pair that shares a body into one function with .withAsync("name"). See the threading section in references/migration-map.md.

  • Do not use @ViewProps, @ExpoView, or @Event(sync: true). The plugin implements them, but SDK 58 core does not declare the two view macros and has no runtime support for synchronous events, so none of them builds. Keep 1.0 views on the DSL. Check the installed core for each of these instead of trusting a plugin version. references/compatibility.md has the per-capability checks.

  • Keep the OnAppContextDestroys, OnAppEntersForeground, OnAppEntersBackground, and OnAppBecomesActive components in definition(). 2.0 has no hook for them.

  • Keep the JS payload of every event. A () -> Void @Event sends undefined, but a 1.0 sendEvent("name") without a body sent {}. When JS code reads that payload, give the event an empty @Record payload type, which encodes to {}, or ask the user before you change it.

  • Keep expo-module.config.json as it is. When it has an apple.modules list (even an empty one), autolinking links only those classes. The entries are bare Swift class names, so renaming a class during migration detaches the module silently: it builds, then is absent at runtime. Without the list, autolinking links the public or open @ExpoModule classes that it finds in the package sources. It does not find a class that is still on the 1.0 DSL alone. A migrated class must stay public or open in both cases. Remove the list only when the user asks and every module class qualifies.

  • Do not change Kotlin, JS wrappers, or public .d.ts files unless the user requested an API change.

  • Never write macro-generated symbols into the module's source. The macro emits them; hand-writing or overriding them is not part of a migration.

After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.

When a 2.0 equivalent is missing or a group fails

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:

  1. Ask the user how to proceed for that item, with two options:

    • Co-exist: keep the item in the 1.0 definition() DSL alongside the migrated @ExpoModule (mixed mode) and continue with the other groups.

    • Revert: back out the group's edits, leaving it untouched on 1.0, and move on.

    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.

  2. 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:

    • the 1.0 member and its JS contract

    • the specific macro or core hook that is missing (cite the evidence gap from references/compatibility.md)

    • the installed expo version, or the expo-modules-core branch when the module builds against a checkout

    Reference 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.

4. Verify behavior

Run the narrowest available checks first, then the real integration surface:

  1. Run npx --no-install expo-modules swift:check ios from the module package root. It reports macro errors and warnings in seconds, without a build. references/compatibility.md describes it.

  2. Build or type-check the Apple module against the target expo-modules-core.

  3. Run native unit tests and JS/TS tests.

  4. Build and launch the example app when the repository provides one.

  5. Confirm that autolinking still links every module class. With an apple.modules list, each entry must match a Swift class name as it now stands. Without the list, run the scanModules check in references/compatibility.md and confirm that it reports every class as public or open. A stale entry or a missed class builds clean and fails only at runtime, so the example app must actually resolve the module, not merely compile.

  6. Compare the final exported surface with the inventory from step 1. The scanExports check in references/compatibility.md lists the JS names, parameters, and sync/async shape of every migrated member. Members that stay in the DSL are not in its output.

  7. Search for stale Name, migrated Function/AsyncFunction/StaticFunction/StaticAsyncFunction/Property/Constant/Events entries, old sendEvent calls, @Field, and duplicate registrations. Search the source you wrote, not macro expansion output.

Expansion alone is insufficient: swift:check runs only the macros, so generated code with no diagnostics can still fail to link or run against a mismatched core. 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.

Handoff

Never print macro-generated or core-internal symbol names to the user. references/compatibility.md cites them so you can grep for them, and the swift:expand output is full of them, but they are implementation details that change between plugin revisions, and they are noise in a report. Name a capability by its macro (@JS static, @Event(sync:)) and by observable JS behavior. Say "the installed core does not support synchronous events yet", not the name of the missing method. The exception is a tracking issue on expo/expo, where the specific missing hook is the point.

Report:

  • which members moved to 2.0

  • which members intentionally remain in the 1.0 DSL and why

  • any compatibility-sensitive choices, especially event names, record requiredness, constants, and queues

  • the commands run and any verification not completed

Submitting Feedback

If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:

npx --yes @expo/agent-cli@latest feedback --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 agent repeatedly fails at an Expo task or the user has to step in, submit a brief report of the task, expected result, and what went wrong using --category evals and the relevant Expo package or command as --subject.

Files

references/example.md

Worked Example: Full Module Migration

This walks a single small module from the 1.0 DSL through mixed mode to a fully migrated 2.0 form. Every per-member rule lives in migration-map.md; this shows how they compose and how mixed mode is an intermediate state, not a failure.

The module below is representative: a name, a sync function, two async functions (one that suspends, one that blocks), a settable property, a constant, an event with observing hooks, and a record.

Starting point: 1.0 DSL

import ExpoModulesCore

@Record
struct DownloadOptions {
  var url: URL              // required
  var retries: Int = 3      // omittable, default 3
  var label: String?        // omittable and nullable
}

public final class DownloaderModule: Module {
  private var volume: Double = 1

  public func definition() -> ModuleDefinition {
    Name("Downloader")

    Events("onProgress")

    OnStartObserving {
      self.beginProgressUpdates()
    }

    OnStopObserving {
      self.stopProgressUpdates()
    }

    Constant("buildInfo") { computeBuildInfo() }

    Function("clamp") { (value: Double) -> Double in
      return min(max(value, 0), 1)
    }

    Property("volume") { self.volume }
      .set { self.volume = $0 }

    AsyncFunction("download") { (options: DownloadOptions) -> String in
      return try await self.performDownload(options)
    }

    AsyncFunction("clearCache") {
      try FileManager.default.removeItem(at: self.cacheDirectory)
    }
  }

  private func report(percent: Double) {
    sendEvent("onProgress", ["percent": percent])
  }
}

The observable contract to preserve:

MemberJS nameContract
ModuleDownloaderrequireNativeModule("Downloader")
clampclampsync, 1 arg, returns number
volumevolumeread/write number
buildInfobuildInforead-only constant
downloaddownloadasync, 1 record arg, returns string
clearCacheclearCacheasync, no args, blocking work runs off the JS thread
onProgressonProgressevent, payload { percent }
observing hooksn/aprogress updates start/stop with the listener count
DownloadOptionsn/aurl required; retries default 3; label nullable

Intermediate: mixed mode

SDK 58 core supports everything used above: @ExpoModule, @JS functions/properties/constants, async @JavaScriptActor, @JS(.concurrent), @Record, default async @Event, and the module lifecycle hooks. One member still needs a decision, by semantics rather than support: clearCache has a body that blocks and never suspends, and a 1.0 AsyncFunction runs it on a background queue automatically, while a 2.0 async member starts on the JS actor. Migrating it as-is would move blocking I/O onto the JS thread, so it stays in the DSL until its group is migrated deliberately.

The record migrates first because it is a pure data type and the function that consumes it depends on it. Its shape is already correct, so migration is just verifying each field decodes: url, retries, label all map cleanly, so @Record stays as-is (it was already using the macro here).

import ExpoModulesCore

@Record
struct DownloadOptions {
  var url: URL
  var retries: Int = 3
  var label: String?
}

@ExpoModule("Downloader")
public final class DownloaderModule: Module {
  // Explicit wire name: default @Event would strip "on" and emit "progress".
  @Event("onProgress")
  var onProgress: (ProgressEvent) -> Void

  @JS("clamp")
  func clamp(value: Double) -> Double {
    return min(max(value, 0), 1)
  }

  // Stored var -> JS getter + setter, matching the 1.0 get/set pair.
  @JS
  var volume: Double = 1

  // Read-only from JS, evaluated at the first read and cached, like the 1.0 Constant.
  @JS
  lazy var buildInfo = computeBuildInfo()

  @JS
  func download(options: DownloadOptions) async throws -> String {
    return try await performDownload(options)
  }

  // override: the hooks are inherited from the Module base class.
  public override func didStartListening(event: String) {
    beginProgressUpdates()
  }

  public override func didStopListening(event: String) {
    stopProgressUpdates()
  }

  // Kept on the DSL: the body blocks without suspending, and a 2.0 async
  // member would start it on the JS actor instead of a background queue.
  public func definition() -> ModuleDefinition {
    AsyncFunction("clearCache") {
      try FileManager.default.removeItem(at: self.cacheDirectory)
    }
  }

  private func report(percent: Double) {
    onProgress(ProgressEvent(percent: percent))
  }
}

@Record
struct ProgressEvent {
  var percent: Double
}

Notes on the choices, each traceable to migration-map.md:

  • Name("Downloader") moved into @ExpoModule("Downloader"); the custom name is carried explicitly, never dropped.

  • @Event("onProgress") uses the explicit wire name to avoid the on-stripping default; the untyped dictionary became a typed ProgressEvent.

  • The duplicate private var volume field was removed once @JS var volume became the single source of truth. Watch for this: a 1.0 backing field plus a migrated @JS var of the same name is a double-declaration.

  • Constant("buildInfo") became @JS lazy var buildInfo. Both evaluate at the first read from JS and cache the value, so the evaluation time does not change. A @JS let would evaluate when the module is created.

  • OnStartObserving/OnStopObserving became the didStartListening(event:)/didStopListening(event:) hooks, with public override because the class inherits Module and is public. The 1.0 hooks were module-wide, so the event argument is ignored.

  • definition() remains but now holds only the queue-sensitive clearCache. It is not deleted because it is non-empty.

  • The class name did not change, so the package's expo-module.config.json entry ("apple": { "modules": ["DownloaderModule"] }) stays valid and is left as it is.

Fully migrated (after explicitly moving the blocking work off the JS actor)

The DSL entry for clearCache was the semantics-preserving default. To finish the migration, migrate it with @JS(.concurrent), so the blocking body still never runs on the JS thread, then delete the empty definition().

import ExpoModulesCore

@Record
struct DownloadOptions {
  var url: URL
  var retries: Int = 3
  var label: String?
}

@Record
struct ProgressEvent {
  var percent: Double
}

@ExpoModule("Downloader")
public final class DownloaderModule: Module {
  @Event("onProgress")
  var onProgress: (ProgressEvent) -> Void

  @JS("clamp")
  func clamp(value: Double) -> Double {
    return min(max(value, 0), 1)
  }

  @JS
  var volume: Double = 1

  @JS
  lazy var buildInfo = computeBuildInfo()

  @JS
  func download(options: DownloadOptions) async throws -> String {
    return try await performDownload(options)
  }

  // The body blocks without suspending, so it runs off the JS thread.
  @JS(.concurrent)
  func clearCache() async throws {
    try FileManager.default.removeItem(at: cacheDirectory)
  }

  public override func didStartListening(event: String) {
    beginProgressUpdates()
  }

  public override func didStopListening(event: String) {
    stopProgressUpdates()
  }

  private func report(percent: Double) {
    onProgress(ProgressEvent(percent: percent))
  }
}

definition() is gone only because it was empty and @ExpoModule("Downloader") preserves the resolved name. If any member had stayed blocked or unverified, the mixed-mode form above is the correct place to stop, not a broken end state.

.concurrent sends the module off the JS thread, so in Swift 6 language mode the class needs @unchecked Sendable, as the .concurrent constraints in migration-map.md describe. The off-thread body reads only cacheDirectory, so the conformance is safe as long as cacheDirectory does not change. volume stays on the JS thread.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

  • Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Expo
Publisher
Expo (Official)
Source
expo/skills · plugins/expo-experiments/skills/expo-migrate-module · commit a9e5bd3
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Expo.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download expo-migrate-module.zip