expo-module

Expo モジュールの作成

Expo Modules API を使用してネイティブモジュールやビューを構築するための完全なリファレンスです。Swift（iOS）、Kotlin（Android）、TypeScript を扱います。

使用する場面

• 新しい Expo ネイティブモジュールやネイティブビューを作成する
• Expo アプリにネイティブ機能（カメラ、センサー、システム API）を追加する
• React Native で利用できるよう、プラットフォーム SDK をラップする
• ネイティブプロジェクトファイルを変更する設定プラグインを構築する
• 既存の Expo モジュールに Android、Apple、または Web のサポートを追加する
• expo-module.config.json、設定プラグイン、またはライフサイクルフックを編集する

既存の Swift モジュールを定義 DSL から Expo Modules API 2.0 マクロ（@ExpoModule、@JS、@Event）に移行する場合は、expo-experiments プラグインの expo-migrate-module スキルを使用してください。

リファレンス

必要に応じて、以下のリソースを参照してください。

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

クイックスタート

ネイティブモジュールのファイルやディレクトリを手動で作成するより、create-expo-module を使用してください。実際には、まずスキャフォールドを作成し、それを土台に構築するのが最善の方法です。スキャフォールドでは、想定されるディレクトリ構成、expo-module.config.json、podspec または Gradle ファイル、TypeScript バインディング、スタンドアロンのサンプルアプリのフローが設定されます。

既存の Expo モジュールに別のプラットフォームを追加するだけの場合は、ネイティブディレクトリを手動でコピーする代わりに、create-expo-module add-platform-support を使用してください。

モジュールをスキャフォールドしたり拡張したりする前に、references/create-expo-module.md を参照してください。以下の内容を説明しています。

• ローカルモジュールとスタンドアロンモジュール
• --platform、--features、--barrel、--package-manager、および非対話モード
• expo.autolinking.nativeModulesDir
• add-platform-support の動作と注意点

推奨ワークフロー

1. まずスキャフォールドの種類を選びます。
   • ローカルモジュール：1 つのアプリで使用する場合
   • スタンドアロンモジュール：再利用、モノレポ、または公開する場合
2. 必要となるネイティブの expo-module 機能を判断します。
   • ユーザーの指示に基づき、どの機能のスキャフォールドが役立つかを判断します。
   • 利用できる機能：Constant、Function、AsyncFunction、Event、View、ViewEvent、SharedObject
3. 意図を持ってスキャフォールドします。
   • 明示的なスラッグまたはパスを指定します
   • デフォルトに任せず、意図的に --platform を選択します
   • --features でコードサンプルを選択し、次の手順で実際の実装に合わせて変更します
4. 生成されたサンプルコードを実際の実装に置き換えます。
5. 後から新しいプラットフォームを追加する場合は、ファイルを手動でコピーするより add-platform-support を優先してください。

実践的なスキャフォールドのルール

• 機能のサンプルはオプトインです。機能を選択しない場合、新しくスキャフォールドされたモジュールは最小限の構成になることがあります。
• ViewEvent は View を含みます。
• ローカルモジュールでは、デフォルトで index.ts のバレルファイルは生成されません。必要な場合にのみ --barrel を使用してください。
• 非対話型でローカルモジュールをスキャフォールドする場合は、位置引数でスラッグまたはパスを明示的に指定してください。--name が変更するのはネイティブクラス名であり、フォルダー名ではありません。
• ローカルモジュールは、設定されている場合は expo.autolinking.nativeModulesDir に配置され、設定されていない場合は modules/ に配置されます。
• スタンドアロンモジュールには独自のパッケージメタデータとスクリプトがあり、通常はサンプルアプリも含まれます。ローカルモジュールではホストアプリのツールを使用します。

コアファイルの構成

Swift と Kotlin の DSL は同じ構造を共有します。通常、Swift が最もわかりやすい主要な例です。機能固有の詳細については、リファレンスを参照してください。

モジュール構造のリファレンス

Swift と Kotlin の DSL は同じ構造を共有します。参考として両方のプラットフォームを示します。他のリファレンスファイルでは、Kotlin のパターンが大きく異なる場合を除き、主要な言語として Swift を示しています。

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"]
  }
}

注：iOS ではクラス名のみを使用します。Android では完全修飾クラス名（パッケージ名 + クラス名）を使用します。すべてのフィールドについては、references/module-config.md を参照してください。

フィードバックの送信

このスキルにエラー、誤解を招く情報、または古い情報がある場合は、Expo の改善に役立てるため報告してください。

npx --yes @expo/agent-cli@latest feedback --category skills --subject "expo-module" "<actionable feedback>"

具体的で実行可能な内容がある場合にのみ送信してください。関連するコンテキストをできるだけ詳しく含めてください。 エージェントが Expo のタスクに繰り返し失敗した場合や、ユーザーが介入する必要があった場合は、タスクの内容、期待される結果、問題の内容を簡潔に報告し、--category evals と、関連する Expo パッケージまたはコマンドを --subject として指定してください。