expo-migrate-module

Name: expo-migrate-module
Author: expo

521installs117forks

How to install expo-migrate-module?

expo/skills/expo-migrate-module

$npx -y skills add expo/skills --skill expo-migrate-module

Installs into the current project.

Summary

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, @Ev

Files · 1

View on GitHub

SKILL.md

1	# Migrate an Expo Module
2
3	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.
4
5	## Prerequisite
6
7	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.
8
9	## References
10
11	- Read `references/migration-map.md` before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.
12	- 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.
13	- 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 an SDK number.
14
15	## Workflow
16
17	### 1. Establish the contract
18
19	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`.
20
21	Inventory every exported item before rewriting it:
22
23	- module and shared-object JS names
24	- function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue semantics
25	- property names, mutability, and constant caching behavior
26	- event wire names and payload shapes
27	- record field names, defaults, requiredness, and nullability
28	- shared-object constructors and instance/static placement
29	- lifecycle hooks and views
30
31	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.
32
33	### 2. Verify the available 2.0 surface
34
35	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.
36
37	Classify each 1.0 item as:
38
39	- Migrate: both its macro and required core runtime support exist.
40	- Keep in DSL: mixed mode preserves it safely, or 2.0 lacks an equivalent.
41	- Blocked: migration would alter the JS contract or requires unavailable runtime support.
42
43	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`.
44
45	### 3. Apply the migration
46
47	Migrate one semantic group at a time: module naming, functions, properties/constants, events, shared objects, then records. Keep the diff narrow.
48
49	Follow these invariants:
50
51	- Preserve every existing JS-visible name explicitly when Swift naming rules or macro defaults differ.
52	- Keep original optional/default behavior. An optional 1.0 record field must not become required merely because 2.0 can express required fields.
53	- Do not migrate same-JS-name overloads unless the checked-out macro groups and dispatches them.
54	- Do not migrate queue-pinned DSL functions as-is; restructure onto Swift Concurrency or dispatch to the original queue via a continuation, per the async-function rules in `references/migration-map.md`.
55	- Do not migrate views, unions, synchronous events, or shared-object static functions without verified support.
56	- Do not change Kotlin, JS wrappers, or public `.d.ts` files unless the user requested an API change.
57
58	After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.
59
60	### When a 2.0 equivalent is missing or a group fails
61
62	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:
63
64	1. Ask the user how to proceed for that item, with two options:
65	- Co-exist: keep the item in the 1.0 `definition()` DSL alongside the migrated `@ExpoModule` (mixed mode) and continue with the other groups.
66	- Revert: back out the group'

People who liked this also viewed

6 picks

Type

expo-migrate-module

521installs117forks

View on GitHub

How to install expo-migrate-module?

expo/skills/expo-migrate-module

$npx -y skills add expo/skills --skill expo-migrate-module

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Migrate an Expo Module
2
3	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.
4
5	## Prerequisite
6
7	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.
8
9	## References
10
11	- Read `references/migration-map.md` before changing source. It contains the 1.0-to-2.0 mappings, semantic traps, and mixed-mode rules.
12	- 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.
13	- 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 an SDK number.
14
15	## Workflow
16
17	### 1. Establish the contract
18
19	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`.
20
21	Inventory every exported item before rewriting it:
22
23	- module and shared-object JS names
24	- function names, arity, labels, defaults, nullability, sync/async behavior, errors, and queue semantics
25	- property names, mutability, and constant caching behavior
26	- event wire names and payload shapes
27	- record field names, defaults, requiredness, and nullability
28	- shared-object constructors and instance/static placement
29	- lifecycle hooks and views
30
31	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.
32
33	### 2. Verify the available 2.0 surface
34
35	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.
36
37	Classify each 1.0 item as:
38
39	- Migrate: both its macro and required core runtime support exist.
40	- Keep in DSL: mixed mode preserves it safely, or 2.0 lacks an equivalent.
41	- Blocked: migration would alter the JS contract or requires unavailable runtime support.
42
43	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`.
44
45	### 3. Apply the migration
46
47	Migrate one semantic group at a time: module naming, functions, properties/constants, events, shared objects, then records. Keep the diff narrow.
48
49	Follow these invariants:
50
51	- Preserve every existing JS-visible name explicitly when Swift naming rules or macro defaults differ.
52	- Keep original optional/default behavior. An optional 1.0 record field must not become required merely because 2.0 can express required fields.
53	- Do not migrate same-JS-name overloads unless the checked-out macro groups and dispatches them.
54	- Do not migrate queue-pinned DSL functions as-is; restructure onto Swift Concurrency or dispatch to the original queue via a continuation, per the async-function rules in `references/migration-map.md`.
55	- Do not migrate views, unions, synchronous events, or shared-object static functions without verified support.
56	- Do not change Kotlin, JS wrappers, or public `.d.ts` files unless the user requested an API change.
57
58	After each group, search for old DSL entries and call sites that should have moved. Avoid broad formatting or unrelated cleanup.
59
60	### When a 2.0 equivalent is missing or a group fails
61
62	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:
63
64	1. Ask the user how to proceed for that item, with two options:
65	- Co-exist: keep the item in the 1.0 `definition()` DSL alongside the migrated `@ExpoModule` (mixed mode) and continue with the other groups.
66	- Revert: back out the group'

People who liked this also viewed

6 picks

Type