AGENT SKILL

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-01
Stars
★ 6
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

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 mode
  • expo.autolinking.nativeModulesDir
  • add-platform-support behavior and quirks

Recommended Workflow

  1. Choose the scaffold type first:
    • Local module for one app
    • Standalone module for reuse, monorepos, or publishing
  2. Determine native expo-module features 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
  3. Scaffold deliberately:
    • pass an explicit slug or path
    • choose --platform intentionally instead of relying on defaults
    • use --features to choose code samples which you will modify in the next step to match the real implementation.
  4. Replace generated example code with the real implementation.
  5. If you add a new platform later, prefer add-platform-support over manual file copying.

Practical Scaffolding Rules

  • Feature examples are opt-in. A newly scaffolded module may be minimal if no features were selected.
  • ViewEvent implies View.
  • Local modules do not generate an index.ts barrel by default. Use --barrel only if you want one.
  • In non-interactive local scaffolding, pass the positional slug or path explicitly. --name changes the native class name, not the folder name.
  • Local modules live in expo.autolinking.nativeModulesDir when configured, otherwise in modules/.
  • 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. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.

04 同仓库更多 Skills

markPie29
markPie29/marky-skills

vercel-react-best-practices

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

★ 6
markPie29
markPie29/marky-skills

ui-styling

Create beautiful, accessible user interfaces with shadcn/ui components (built on Radix UI + Tailwind), Tailwind CSS utility-first styling, and canvas-based visual designs. Use when building user interfaces, implementing design systems, creating responsive layouts, adding accessible components (dialogs, dropdowns, forms, tables), customizing themes and colors, implementing dark mode, generating visual designs and posters, or establishing consistent styling patterns across applications.

★ 6
markPie29
markPie29/marky-skills

tauri

Comprehensive index for Tauri framework development, including Rust backend, frontend integration, and full plugin ecosystem. Acts as a router to specialized sub-skills with local examples and templates.

★ 6
markPie29
markPie29/marky-skills

tauri-window

Guidance for Tauri v2 window creation, configuration, lifecycle management, and custom titlebar UI.

★ 6
markPie29
markPie29/marky-skills

tauri-setup

Guidance for Tauri v2 prerequisites and environment setup across macOS, Windows, Linux, and mobile Android iOS targets.

★ 6
markPie29
markPie29/marky-skills

tauri-security

Guidance for Tauri v2 capabilities, scope configuration, and ACL-based permission control.

★ 6