expo-module
Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.
- License 许可
- MIT
- 最近更新
- 2026-09-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- expo-module
- license
- MIT
- version
- 1.0.0
- description
- Framework (OSS). Guide for creating and writing Expo native modules and views using the Expo Modules API (Swift, Kotlin, TypeScript). Covers module definition DSL, native views, shared objects, config plugins, lifecycle hooks, autolinking, and type system. Use when building or modifying native modules for Expo. Not for migrating an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros; use expo-migrate-module (from the expo-experiments plugin) for that.
02 资源文件 7
- 参考文档agents/openai.yaml367 B
- 参考文档references/config-plugin.md2.0 KB
- 参考文档references/create-expo-module.md9.8 KB
- 参考文档references/lifecycle.md3.7 KB
- 参考文档references/module-config.md1.7 KB
- 参考文档references/native-module.md5.7 KB
- 参考文档references/native-view.md3.5 KB
03 SKILL.md 正文
Writing Expo Modules
Complete reference for building native modules and views using the Expo Modules API. Covers Swift (iOS), Kotlin (Android), and TypeScript.
When to Use
- Creating a new Expo native module or native view
- Adding native functionality (camera, sensors, system APIs) to an Expo app
- Wrapping platform SDKs for React Native consumption
- Building config plugins that modify native project files
- Adding Android, Apple, or web support to an existing Expo module
- Editing
expo-module.config.json, config plugins, or lifecycle hooks
To migrate an existing Swift module from the definition DSL to the Expo Modules API 2.0 macros (@ExpoModule, @JS, @Event), use the expo-migrate-module skill (from the expo-experiments plugin) instead.
References
Consult these resources as needed:
references/
create-expo-module.md Scaffolding and add-platform-support workflow, defaults, and quirks
native-module.md Module definition DSL: Name, Function, AsyncFunction, Property, Constant, Events, type system, shared objects
native-view.md Native view components: View, Prop, EventDispatcher, view lifecycle, ref-based functions
lifecycle.md Lifecycle hooks: module, iOS app/AppDelegate, Android activity/application listeners
config-plugin.md Config plugins: modifying Info.plist, AndroidManifest.xml, reading values in native code
module-config.md expo-module.config.json fields, file placement, and autolinking behavior
Quick Start
Prefer create-expo-module over manually creating native module files and directories. In practice, the best path is usually to create the scaffold first and then build on top of it. The scaffold sets up the expected layout, expo-module.config.json, podspec or Gradle files, TypeScript bindings, and the standalone example app flow.
If an existing Expo module only needs another platform, use create-expo-module add-platform-support instead of manually copying native directories.
See references/create-expo-module.md before scaffolding or extending a module. It covers:
- local vs standalone modules
--platform,--features,--barrel,--package-manager, and non-interactive modeexpo.autolinking.nativeModulesDiradd-platform-supportbehavior and quirks
Recommended Workflow
- Choose the scaffold type first:
- Local module for one app
- Standalone module for reuse, monorepos, or publishing
- Determine native
expo-modulefeatures that you will need.- Based on the user's instructions determine which feature scaffolding will be useful.
- Available features:
Constant,Function,AsyncFunction,Event,View,ViewEvent,SharedObject
- Scaffold deliberately:
- pass an explicit slug or path
- choose
--platformintentionally instead of relying on defaults - use
--featuresto choose code samples which you will modify in the next step to match the real implementation.
- Replace generated example code with the real implementation.
- If you add a new platform later, prefer
add-platform-supportover manual file copying.
Practical Scaffolding Rules
- Feature examples are opt-in. A newly scaffolded module may be minimal if no features were selected.
ViewEventimpliesView.- Local modules do not generate an
index.tsbarrel by default. Use--barrelonly if you want one. - In non-interactive local scaffolding, pass the positional slug or path explicitly.
--namechanges the native class name, not the folder name. - Local modules live in
expo.autolinking.nativeModulesDirwhen configured, otherwise inmodules/. - Standalone modules have their own package metadata, scripts, and usually an example app. Local modules use the host app's tooling instead.
Core File Shapes
The Swift and Kotlin DSL share the same structure. Swift is usually the clearest primary example; consult the references for feature-specific details.
Module Structure Reference
The Swift and Kotlin DSL share the same structure. Both platforms are shown here for reference — in other reference files, Swift is shown as the primary language unless the Kotlin pattern meaningfully differs.
Swift (iOS):
import ExpoModulesCore
public class MyModule: Module {
public func definition() -> ModuleDefinition {
Name("MyModule")
Function("hello") { (name: String) -> String in
return "Hello \(name)!"
}
}
}
Kotlin (Android):
package expo.modules.mymodule
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
class MyModule : Module() {
override fun definition() = ModuleDefinition {
Name("MyModule")
Function("hello") { name: String ->
"Hello $name!"
}
}
}
TypeScript:
import { requireNativeModule } from "expo";
const MyModule = requireNativeModule("MyModule");
export function hello(name: string): string {
return MyModule.hello(name);
}
expo-module.config.json
{
"platforms": ["android", "apple"],
"apple": {
"modules": ["MyModule"]
},
"android": {
"modules": ["expo.modules.mymodule.MyModule"]
}
}
Note: iOS uses just the class name; Android uses the fully-qualified class name (package + class). See references/module-config.md for all fields.
Submitting Feedback
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-module" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible.
04 同仓库更多 Skills
widget-custom-fonts
Bundle custom fonts into iOS widget extensions (expo-widgets) — expo-font only covers the main app target, not the widget extension
troubleshoot
Known bugs, quirks, and their fixes discovered during development
set-app-identity
Sweep every file that carries app identity (name, bundle id, scheme, URLs, emails, entitlement IDs, DB filename, EAS project, theme colors) and update them in one consistent pass when renaming/rebranding an expo-starter project. Use when the user says 'rename the app', 'rebrand', 'change app identity', 'update bundle id', 'set up identity for a new project', 'customize the template', or otherwise needs to replace the placeholder identity shipped with expo-starter. Covers app.config.ts BASE_* constants, package.json name, constants/index WEB_URL, lib/mail SUPPORT_EMAIL, constants/revenuecat ENTITLEMENT_ID, db/app/index DB filename, maestro appId, paywall plan names, tailwind theme colors, and EAS project config.
react-native-best-practices
Software Mansion's best practices for production React Native and Expo apps on the New Architecture. MUST USE before writing, reviewing, or debugging ANY code in a React Native or Expo project. If the working directory contains a package.json with react-native, expo, or expo-router as a dependency, this skill applies. Trigger on: any code task in a React Native/Expo project, 'React Native', 'Expo', 'New Architecture', 'Reanimated', 'Gesture Handler', 'react-native-svg', 'ExecuTorch', 'react-native-audio-api', 'react-native-enriched', 'Worklet', 'Fabric', 'TurboModule', 'WebGPU', 'react-native-wgpu', 'TypeGPU', 'GPU shader', 'WGSL', 'svg', 'animation', 'gesture', 'audio', 'rich text', 'AI model', 'multithreading', 'chart', 'vector', 'image filter', 'shared value', 'useSharedValue', 'runOnJS', 'scheduleOnRN', 'thread', 'worklet', 'Bundle Mode', or any question involving UI, graphics, native modules, or React Native threading and animation behavior. Also use when a more specific sub-skill matches.
motion-design
Applies motion design principles to create emotionally-driven, technically sound animations and transitions. Provides timing, easing, choreography, and Disney animation principles adapted for UI. Use when creating animations, transitions, micro-interactions, loading states, page transitions, scroll-triggered effects, or any motion work. Works with CSS, Framer Motion, GSAP, Lottie, Spring, or any animation system.
expo-web-to-native
Framework (OSS). Migrate an existing web React app to a native iOS/Android app with Expo. Use when the user wants to turn a website into a mobile app, port a Next.js/Vite/CRA React codebase to React Native, reuse web code on native incrementally, or asks how web idioms (the DOM, CSS, React Router, localStorage, window) map to native. This is the end-to-end migration guide; use the `expo-dom` skill for the DOM-component mechanism itself.