--- name: expo-module description: "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." risk: critical source: https://github.com/expo/skills/tree/main/plugins/expo/skills/expo-module source_repo: expo/skills source_type: official date_added: 2026-07-01 license: MIT license_source: https://github.com/expo/skills/blob/main/LICENSE --- # 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 ## 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 ``` ## Native integration limits Pin the scaffold and Expo SDK versions and verify available CLI options before running them. These native modules require a development/rebuilt native app; adding native code is not an Expo Go or OTA-only update. Preserve native modifications before prebuild, request platform permissions with accurate purpose strings, and validate native inputs, lifecycle cleanup and thread affinity on both platforms. Snippets omit imports/helpers and are not a compiled package. ## 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](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):** ```swift import ExpoModulesCore public class MyModule: Module { public func definition() -> ModuleDefinition { Name("MyModule") Function("hello") { (name: String) -> String in return "Hello \(name)!" } } } ``` **Kotlin (Android):** ```kotlin 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:** ```typescript import { requireNativeModule } from "expo"; const MyModule = requireNativeModule("MyModule"); export function hello(name: string): string { return MyModule.hello(name); } ``` ### expo-module.config.json ```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. ## Limitations - Use this skill only when the task clearly matches its upstream product or API scope. - Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes. - Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions. --- Source attribution: expo/skills contributors, via Agentic Awesome Skills Original project: https://github.com/expo/skills License: MIT + CC-BY-4.0 License information: https://creativecommons.org/licenses/by/4.0/ Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice The MIT License (MIT) Copyright (c) 2025-present 650 Industries, Inc. (aka Expo) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: expo/skills contributors, via Agentic Awesome Skills Original project: https://github.com/expo/skills Attribution basis: Recorded upstream repository Fields of work: Development & Engineering Roles: Mobile Developer Specialties: Specialty not specified Tools: Tool not specified Country applicability: Country not specified Classification basis: Dave AI task classification from package title, description, and declared metadata Instruction SHA-256: 8f0de33a0f95946a8bfd7cf375b4bba18d7d3556205abc9da62e4cf96f51dc76 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.