\n\n`@expo/expo-modules-macros-plugin` is the Swift compiler plugin behind the Expo Modules API. It implements the macros that [`expo-modules-core`](https://github.com/expo/expo/tree/main/packages/expo-modules-core) declares, so a module author writes plain Swift declarations and the plugin synthesizes the code that binds them to JavaScript.\n\nThe same executable doubles as a source scanner CLI.\n\n# Installation\n\nThis package is not meant to be installed directly. It is a dependency of `expo-modules-core`, so every Expo project already has it. The published package contains a prebuilt universal (arm64 + x86_64) macOS binary at `apple/ExpoModulesMacros-tool`, so consumers never build the plugin themselves.\n\n# Macros\n\n- **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none.\n- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it.\n- **`@Event(_ name: String? = nil, sync: Bool = false)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `sync: true` dispatches inline instead of asynchronously.\n- **`@SharedObject(_ name: String? = nil)`** on a `SharedObject` subclass. Collects the class's `@JS` members into a class definition that a module exposes through `@ExpoModule(classes:)`.\n- **`@Record()`** on a record type. Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.\n- **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.\n\nHow that looks in a module:\n\n```swift\nimport ExpoModulesCore\n\n@ExpoModule(classes: [Cache.self])\npublic final class MyModule {\n @JS\n func greet(name: String) -> String {\n \"Hi, \\(name)\"\n }\n\n @JS(\"doWork\")\n func performWork() async throws { ... }\n\n @Event\n var onProgress: (ProgressEvent) -> Void\n}\n\n@SharedObject\nfinal class Cache: SharedObject {\n @JS\n init(name: String) { ... }\n\n @JS\n func get(_ key: String) -> String? { ... }\n}\n```\n\nThe author-facing documentation for each macro lives next to its declaration in `expo-modules-core`, in `ios/Core/ExpoModulesMacros.swift`. This repository holds the implementations.\n\n# Scanner\n\nThe Swift compiler launches a plugin executable with no arguments and speaks the plugin protocol over stdin, so the binary treats any argument as a scanner invocation instead:\n\n```\nExpoModulesMacros-tool [options] [ ...]\n\nsubcommands:\n scan-modules fast scan for top-level @ExpoModule types (autolinking)\n scan-exports deep scan of the full JS-exported surface (type generation)\n\noptions (scan-modules only):\n --platform evaluate '#if os(...)' against this platform\n --define treat a conditional compilation flag as set; repeatable\n```\n\nEach path is a `.swift` file or a directory, scanned recursively for `.swift` files. Both subcommands print a JSON report to stdout, each carrying its own `schemaVersion` so a consumer can check it understands the shape before trusting it. The two versions are independent: the commands serve different consumers and change for different reasons.\n\n# TypeScript wrapper\n\nNode consumers can call the scanner through this package instead of locating the binary and shelling out themselves:\n\n```ts\nimport { scanModules, scanExports } from '@expo/expo-modules-macros-plugin';\n\nconst { modules, warnings } = await scanModules(['ios/'], { defines: ['DEBUG'] });\nconst { exports } = await scanExports(['ios/']);\n```\n\nThe binary is a compiled executable, so each call still spawns a process. What the wrapper owns is the part consumers would otherwise duplicate: resolving the shipped binary, building the arguments, parsing the JSON, checking `schemaVersion`, and turning a non-zero exit into a `ScannerError`. The result types are hand-written mirrors of the Swift `Codable` types, which is what the version check guards against drifting.\n\n# How the plugin reaches the compiler\n\n`expo-modules-core` declares the macro signatures with `#externalMacro(module: \"ExpoModulesMacros\", type: …)`. During `pod install`, `expo-modules-autolinking` resolves this package from the core package and appends\n\n```\n-Xfrontend -load-plugin-executable -Xfrontend /apple/ExpoModulesMacros-tool#ExpoModulesMacros\n```\n\nto `OTHER_SWIFT_FLAGS` for `ExpoModulesCore`, every pod that depends on it, and their test specs. Expo's SPM prebuilds pass the same flag when they generate `Package.swift`, so both build systems load the same binary.\n\nThe module and type names in `#externalMacro` must stay in sync with `apple/Sources/ExpoModulesMacros/Plugin.swift`.\n\n# Development\n\nRequires macOS 13 or newer and a toolchain with Swift 6.2, which means Xcode 26 or newer.\n\n```sh\ncd apple\nswift build\nswift test\n```\n\n`npm run build` runs `apple/build.js`, which builds the release binary for arm64 and x86_64, merges the slices into `apple/ExpoModulesMacros-tool` with `lipo`, strips it, and verifies both slices are present. SwiftPM only builds macro tools for the host architecture, so the x86_64 slice is produced by running the toolchain under Rosetta; the script installs Rosetta if it is missing. The resulting binary is committed to the repository.\n\n# Releasing\n\nThe **Publish** workflow is manual (`workflow_dispatch`) and takes a release type. It bumps the version, builds the universal binary, and publishes to npm through OIDC trusted publishing. The commit, tag and GitHub release are created only after the publish succeeds, so a failed build leaves the branch untouched.\n\n# Contributing\n\nContributions are very welcome! Please refer to the guidelines described in the [contributing guide](https://github.com/expo/expo#contributing).\n","readmeFilename":"README.md"}