@appsent-co/react-native-watchos 0.1.0

package/package.json

@@ -0,0 +1,131 @@
+{
+  "name": "@appsent-co/react-native-watchos",
+  "version": "0.1.0",
+  "description": "Build WatchOS apps in react-native",
+  "main": "./plugin/src/index.js",
+  "bin": {
+    "react-native-watchos": "./cli/init.js"
+  },
+  "exports": {
+    ".": "./plugin/src/index.js",
+    "./metro-config": {
+      "types": "./metro-config.d.ts",
+      "default": "./metro-config.js"
+    },
+    "./renderer": "./src/index.ts",
+    "./dev-support": "./src/devSupport/index.ts",
+    "./watch-connectivity": "./src/watchConnectivity/index.ts",
+    "./app.plugin.js": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "codegenConfig": {
+    "name": "RNWatchConnectivitySpec",
+    "type": "modules",
+    "jsSrcsDir": "src/watchConnectivity/specs"
+  },
+  "files": [
+    "app.plugin.js",
+    "metro-config.js",
+    "metro-config.d.ts",
+    "react-native.config.js",
+    "RNWatchConnectivity.podspec",
+    "cli",
+    "plugin",
+    "src",
+    "apple",
+    "cocoapods",
+    "build/xcframework",
+    "!**/.*"
+  ],
+  "keywords": [
+    "react-native",
+    "watchos",
+    "apple-watch",
+    "expo",
+    "expo-plugin",
+    "hermes",
+    "swift-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appsent-co/react-native-watchos.git"
+  },
+  "author": "Appsent <maxence@appsent.com> (https://appsent.com)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/appsent-co/react-native-watchos/issues"
+  },
+  "homepage": "https://github.com/appsent-co/react-native-watchos#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@commitlint/config-conventional": "^19.8.1",
+    "@eslint/js": "^9.35.0",
+    "@evilmartians/lefthook": "^1.12.3",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@types/react": "^19.1.0",
+    "@types/react-reconciler": "^0.28.9",
+    "commitlint": "^19.8.1",
+    "del-cli": "^6.0.0",
+    "eslint": "^9.35.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^15.14.0",
+    "prettier": "^3.6.2",
+    "react": "19.1.0",
+    "react-reconciler": "0.32.0",
+    "release-it": "^19.0.4",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "@expo/config-plugins": "^54.0.0",
+    "whatwg-fetch": "^3.6.20"
+  },
+  "peerDependencies": {
+    "@bacons/apple-targets": ">=4.0.0",
+    "expo": ">=54.0.0",
+    "react": "*",
+    "react-native": "*",
+    "react-reconciler": "*"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "release-it": {
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}"
+    },
+    "npm": {
+      "publish": true
+    },
+    "github": {
+      "release": true
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "angular"
+        }
+      }
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "scripts": {
+    "build:xcframework": "./scripts/build-xcframework.sh",
+    "lint": "eslint .",
+    "clean": "del-cli build/xcframework example/ios",
+    "docs": "pnpm --filter react-native-watchos-docs start",
+    "docs:build": "pnpm --filter react-native-watchos-docs build",
+    "release": "release-it --only-version"
+  }
+}

package/plugin/README.md

@@ -0,0 +1,113 @@
+# @appsent-co/react-native-watchos Expo plugin
+
+An Expo Config Plugin that wires the `@appsent-co/react-native-watchos` Swift Package
+(Hermes runtime + JSI host) into the watchOS target generated by
+[`@bacons/apple-targets`](https://github.com/EvanBacon/expo-apple-targets)
+during `expo prebuild`.
+
+## Setup
+
+### 1. Install
+
+```sh
+npx expo install @appsent-co/react-native-watchos @bacons/apple-targets
+```
+
+### 2. Create the watch target
+
+```sh
+npx create-target watch
+```
+
+This creates `targets/watch/` with `expo-target.config.json` containing
+`{ "type": "watch" }` and a starter `index.swift`.
+
+### 3. Configure plugins
+
+In your `app.json` (order matters — `@bacons/apple-targets` must run first):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      "@bacons/apple-targets",
+      ["@appsent-co/react-native-watchos", { "targetName": "watch" }]
+    ]
+  }
+}
+```
+
+The `targetName` option defaults to `"watch"` (matching the directory name
+under `targets/`). If you renamed the target directory, pass that name.
+
+### 4. Drop in the POC ContentView (optional)
+
+If you want a working "fetch a JS bundle and display console output" Watch
+UI out of the box, copy `plugin/templates/ContentView.swift` into your
+`targets/watch/` directory:
+
+```sh
+cp node_modules/@appsent-co/react-native-watchos/plugin/templates/ContentView.swift targets/watch/
+```
+
+It uses `ReactNativeWatchOSHost` from the SPM package to load a JS bundle
+from `http://127.0.0.1:8000/hello.js` and renders `console.log` output in a
+SwiftUI list.
+
+### 5. Prebuild & run
+
+```sh
+npx expo prebuild -p ios --clean
+# In another terminal:
+cp node_modules/@appsent-co/react-native-watchos/plugin/templates/hello.js .
+python3 -m http.server 8000
+# Open Xcode, select the watch scheme, run.
+```
+
+## What the plugin does
+
+During `npx expo prebuild`, after `@bacons/apple-targets` has created the
+watch target in the pbxproj, this plugin:
+
+1. Adds an `XCLocalSwiftPackageReference` pointing at the npm-installed
+   `@appsent-co/react-native-watchos` package (relative path from `<project>/ios/`).
+2. Adds an `XCSwiftPackageProductDependency` for the `ReactNativeWatchOS`
+   library product.
+3. Wires the product into the watch target's `Frameworks` build phase.
+4. Relies on SPM's built-in handling to embed `Hermes.xcframework` (the
+   dynamic JS engine) into the watch app.
+
+The Hermes XCFramework is prebuilt and shipped inside the npm tarball at
+`build/xcframework/Hermes.xcframework`. No `npm install` post-build steps
+required.
+
+## What the plugin does NOT do
+
+- It does not create the watch target itself. `@bacons/apple-targets`
+  handles that with `expo-target.config.json` — bundle ID, signing,
+  deployment target, Info.plist, asset catalogs all flow through there.
+- It does not bundle JS for the watch app — currently the Hermes runtime
+  loads JS dynamically from a URL you provide. (Bundled JS support is a
+  future enhancement.)
+
+## Troubleshooting
+
+**`Target "watch" not found in pbxproj.`** The `@bacons/apple-targets`
+plugin didn't run before us. Make sure it's listed first in
+`expo.plugins` and that `targets/watch/expo-target.config.json` exists.
+
+**`Could not resolve '@appsent-co/react-native-watchos'`.** Run `npm install`. The
+plugin uses `require.resolve` to find the package and the path is
+included in the generated pbxproj as a relative path from `ios/`.
+
+**SPM resolve fails at Xcode build time.** Check that
+`build/xcframework/Hermes.xcframework` and
+`build/xcframework/ReactNativeWatchOSCxx.xcframework` exist inside the
+installed package. If you cloned the repo locally instead of installing
+via npm, run `./scripts/build-xcframework.sh`.
+
+**`No such module 'ReactNativeWatchOS'` in your `ContentView.swift`.**
+SourceKit hasn't indexed the local SPM package yet — usually a Cmd-Shift-K
+clean + rebuild fixes it. If it persists, verify the watch target's
+"Frameworks, Libraries, and Embedded Content" lists `ReactNativeWatchOS`
+in Xcode.

package/plugin/src/index.js

@@ -0,0 +1,69 @@
+// @ts-check
+const { withPlugins } = require('@expo/config-plugins');
+const withSPMPackage = require('./withSPMPackage');
+const withWatchAutolinking = require('./withWatchAutolinking');
+const withWatchBundleScript = require('./withWatchBundleScript');
+const withWatchTurboModuleCodegen = require('./withWatchTurboModuleCodegen');
+
+/**
+ * Expo Config Plugin for `@appsent-co/react-native-watchos`.
+ *
+ * Two pbxproj mods on the watch target that `@bacons/apple-targets`
+ * creates during `expo prebuild`:
+ *   1. `withSPMPackage` — wires the local Swift Package (Hermes + JSI host).
+ *   2. `withWatchBundleScript` — adds a Release-only Run Script Build Phase
+ *      that invokes `expo export:embed --platform watchos` and writes
+ *      `main.jsbundle` into the watch app's resources.
+ *
+ * Recommended app.json:
+ *
+ *   {
+ *     "expo": {
+ *       "plugins": [
+ *         "@bacons/apple-targets",
+ *         ["@appsent-co/react-native-watchos", { "targetName": "watch" }]
+ *       ]
+ *     }
+ *   }
+ *
+ * And `targets/watch/expo-target.config.json`:
+ *
+ *   { "type": "watch" }
+ *
+ * Order matters: `@bacons/apple-targets` MUST run before this plugin so the
+ * watch target exists in the pbxproj when we look it up.
+ *
+ * @typedef {object} ReactNativeWatchOSPluginOpts
+ * @property {string} [targetName] - Name of the watch target in pbxproj.
+ *   Matches `@bacons/apple-targets`' directory-derived name. Defaults to
+ *   `"watch"`.
+ * @property {string} [bundleName] - Output JS bundle filename (without
+ *   extension). Defaults to `"main"` (→ `main.jsbundle`).
+ * @property {string} [entryFile] - Path (relative to project root) of the
+ *   JS entry. Defaults to auto-detecting `index.watchos.{tsx,ts,jsx,js}`
+ *   at build time.
+ * @property {string} [watchosDeploymentTarget] - Minimum watchOS version
+ *   advertised to CocoaPods autolinking. Defaults to `"9.0"`, matching
+ *   `WATCHOS_DEPLOYMENT_TARGET` in `scripts/build-xcframework.sh`.
+ *
+ * @type {import('@expo/config-plugins').ConfigPlugin<ReactNativeWatchOSPluginOpts | void>}
+ */
+const withReactNativeWatchOS = (config, opts) => {
+  const targetName = (opts && opts.targetName) || 'watch';
+  const bundleName = (opts && opts.bundleName) || 'main';
+  const entryFile = opts && opts.entryFile;
+  const watchosDeploymentTarget = opts && opts.watchosDeploymentTarget;
+  return withPlugins(config, [
+    [withSPMPackage, { targetName }],
+    // Run codegen BEFORE the bundle script so the generated sources are
+    // wired into the watch target's pbxproj when Xcode opens it (the
+    // bundle script is a separate Run Script phase that doesn't depend
+    // on codegen output, but ordering keeps the diff readable).
+    [withWatchTurboModuleCodegen, { targetName }],
+    [withWatchAutolinking, { targetName, watchosDeploymentTarget }],
+    [withWatchBundleScript, { targetName, bundleName, entryFile }],
+  ]);
+};
+
+module.exports = withReactNativeWatchOS;
+module.exports.default = withReactNativeWatchOS;

package/plugin/src/withSPMPackage.js

@@ -0,0 +1,287 @@
+// @ts-check
+const fs = require('fs');
+const path = require('path');
+const { withFinalizedMod } = require('@expo/config-plugins');
+
+const SPM_PRODUCT_NAME = 'ReactNativeWatchOS';
+
+/**
+ * Adds a local Swift Package Manager reference to the consumer's iOS Xcode
+ * project pointing at the npm-installed `@appsent-co/react-native-watchos` package, and
+ * wires its `ReactNativeWatchOS` library product as a dependency of the named
+ * watchOS target.
+ *
+ * Implementation note: registered as a `finalized` mod so it runs AFTER
+ * @bacons/apple-targets has finished creating the watch target in the
+ * pbxproj. The finalized mod doesn't provide a parsed pbxproj, so we read /
+ * parse / mutate / write the file directly using the `xcode` library that
+ * Expo ships as a transitive dep.
+ *
+ * @typedef {object} Opts
+ * @property {string} targetName - Name of the watch target in pbxproj.
+ *   Defaults to `"watch"`.
+ *
+ * @param {import('@expo/config-plugins').ExpoConfig} config
+ * @param {Opts} opts
+ */
+const withSPMPackage = (config, { targetName }) => {
+  return withFinalizedMod(config, [
+    'ios',
+    async (cfg) => {
+      const projectRoot = cfg.modRequest.projectRoot;
+      const platformRoot = cfg.modRequest.platformProjectRoot;
+      const pbxprojPath = findPbxproj(platformRoot);
+
+      const xcode = require('xcode');
+      const project = xcode.project(pbxprojPath);
+      await new Promise((resolve, reject) => {
+        project.parse((err) => (err ? reject(err) : resolve()));
+      });
+
+      const objects = project.hash.project.objects;
+
+      // -------------------------------------------------------------
+      // Resolve npm package path relative to <project>/ios
+      // -------------------------------------------------------------
+      let pkgJsonPath;
+      try {
+        pkgJsonPath = require.resolve(
+          '@appsent-co/react-native-watchos/package.json',
+          {
+            paths: [projectRoot],
+          }
+        );
+      } catch (_) {
+        throw new Error(
+          `[@appsent-co/react-native-watchos] Could not resolve '@appsent-co/react-native-watchos' ` +
+            `from ${projectRoot}. Did you run \`npm install\`?`
+        );
+      }
+      // Package.swift lives in <pkgDir>/apple — point SPM at that subdir,
+      // not the npm package root.
+      const pkgDir = path.dirname(pkgJsonPath);
+      const swiftPackageDir = path.join(pkgDir, 'apple');
+      const relPath = path.relative(platformRoot, swiftPackageDir);
+
+      // -------------------------------------------------------------
+      // Find the watch target by name
+      // -------------------------------------------------------------
+      const nativeTargets = objects.PBXNativeTarget || {};
+      let targetKey = null;
+      for (const key of Object.keys(nativeTargets)) {
+        if (key.endsWith('_comment')) continue;
+        const t = nativeTargets[key];
+        if (stripQuotes(t.name) === targetName) {
+          targetKey = key;
+          break;
+        }
+      }
+      if (!targetKey) {
+        const available = Object.keys(nativeTargets)
+          .filter((k) => !k.endsWith('_comment'))
+          .map((k) => stripQuotes(nativeTargets[k].name));
+        throw new Error(
+          `[@appsent-co/react-native-watchos] Target "${targetName}" not found in pbxproj. ` +
+            `Available: [${available.join(', ')}]. ` +
+            `Make sure @bacons/apple-targets is configured and listed before ` +
+            `@appsent-co/react-native-watchos in app.json plugins.`
+        );
+      }
+      const target = nativeTargets[targetKey];
+
+      // Locate the PBXProject node (single one expected)
+      const pbxProjectKey = Object.keys(objects.PBXProject || {}).find(
+        (k) => !k.endsWith('_comment')
+      );
+      if (!pbxProjectKey) {
+        throw new Error(
+          '[@appsent-co/react-native-watchos] No PBXProject found in pbxproj'
+        );
+      }
+      const pbxProject = objects.PBXProject[pbxProjectKey];
+
+      // -------------------------------------------------------------
+      // 1. XCLocalSwiftPackageReference + attach to PBXProject
+      // -------------------------------------------------------------
+      const packageRefId = project.generateUuid();
+      const packageRefComment = `XCLocalSwiftPackageReference "${relPath}"`;
+      objects.XCLocalSwiftPackageReference =
+        objects.XCLocalSwiftPackageReference || {};
+      objects.XCLocalSwiftPackageReference[packageRefId] = {
+        isa: 'XCLocalSwiftPackageReference',
+        relativePath: `"${relPath}"`,
+      };
+      objects.XCLocalSwiftPackageReference[`${packageRefId}_comment`] =
+        packageRefComment;
+
+      pbxProject.packageReferences = pbxProject.packageReferences || [];
+      pbxProject.packageReferences.push({
+        value: packageRefId,
+        comment: packageRefComment,
+      });
+
+      // -------------------------------------------------------------
+      // 2. XCSwiftPackageProductDependency + attach to target
+      // -------------------------------------------------------------
+      const productDepId = project.generateUuid();
+      objects.XCSwiftPackageProductDependency =
+        objects.XCSwiftPackageProductDependency || {};
+      objects.XCSwiftPackageProductDependency[productDepId] = {
+        isa: 'XCSwiftPackageProductDependency',
+        package: packageRefId,
+        package_comment: packageRefComment,
+        productName: SPM_PRODUCT_NAME,
+      };
+      objects.XCSwiftPackageProductDependency[`${productDepId}_comment`] =
+        SPM_PRODUCT_NAME;
+
+      target.packageProductDependencies =
+        target.packageProductDependencies || [];
+      target.packageProductDependencies.push({
+        value: productDepId,
+        comment: SPM_PRODUCT_NAME,
+      });
+
+      // -------------------------------------------------------------
+      // 3. PBXBuildFile referencing the product + Frameworks build phase
+      // -------------------------------------------------------------
+      const buildFileId = project.generateUuid();
+      const buildFileComment = `${SPM_PRODUCT_NAME} in Frameworks`;
+      objects.PBXBuildFile = objects.PBXBuildFile || {};
+      objects.PBXBuildFile[buildFileId] = {
+        isa: 'PBXBuildFile',
+        productRef: productDepId,
+        productRef_comment: SPM_PRODUCT_NAME,
+      };
+      objects.PBXBuildFile[`${buildFileId}_comment`] = buildFileComment;
+
+      let frameworksPhaseKey = null;
+      for (const phaseRef of target.buildPhases || []) {
+        const k = phaseRef.value;
+        if (
+          objects.PBXFrameworksBuildPhase &&
+          objects.PBXFrameworksBuildPhase[k]
+        ) {
+          frameworksPhaseKey = k;
+          break;
+        }
+      }
+      // apple-targets doesn't create a Frameworks build phase for a watch
+      // target by default — it only adds Sources + Resources. Create one
+      // and attach it to the target so we have somewhere to put the SPM
+      // product reference.
+      if (!frameworksPhaseKey) {
+        frameworksPhaseKey = project.generateUuid();
+        objects.PBXFrameworksBuildPhase = objects.PBXFrameworksBuildPhase || {};
+        objects.PBXFrameworksBuildPhase[frameworksPhaseKey] = {
+          isa: 'PBXFrameworksBuildPhase',
+          buildActionMask: 2147483647,
+          files: [],
+          runOnlyForDeploymentPostprocessing: 0,
+        };
+        objects.PBXFrameworksBuildPhase[`${frameworksPhaseKey}_comment`] =
+          'Frameworks';
+        target.buildPhases = target.buildPhases || [];
+        target.buildPhases.push({
+          value: frameworksPhaseKey,
+          comment: 'Frameworks',
+        });
+      }
+      const frameworksPhase =
+        objects.PBXFrameworksBuildPhase[frameworksPhaseKey];
+      frameworksPhase.files = frameworksPhase.files || [];
+      frameworksPhase.files.push({
+        value: buildFileId,
+        comment: buildFileComment,
+      });
+
+      // -------------------------------------------------------------
+      // 4. Apply build settings to the watch target's configs:
+      //    - EXCLUDED_ARCHS[sdk=watchsimulator*] = x86_64
+      //      @appsent-co/react-native-watchos ships XCFramework slices for arm64 only
+      //      (Apple Silicon Macs). Without the exclusion, Xcode tries to
+      //      link an x86_64 watch.dylib and can't find RNWHermesHost.
+      //    - OTHER_LDFLAGS += -lc++
+      //      ReactNativeWatchOSCxx is a static archive containing JSI
+      //      (C++). The Swift consumer target alone doesn't pull in
+      //      libc++, so the watch target's dylib link fails with hundreds
+      //      of std::__1::* undefined symbols. SPM's linkerSettings on
+      //      our Swift target don't reliably propagate into an
+      //      apple-targets-managed target, so we set it here.
+      //    - OTHER_LDFLAGS += -ObjC
+      //      TurboModules auto-register at image load via the `+load`
+      //      synthesized by `RCT_EXPORT_MODULE` (watch fork) and
+      //      `RNW_EXPORT_CXX_MODULE`. The linker dead-strips ObjC classes
+      //      from static libraries unless explicitly referenced; `-ObjC`
+      //      forces every class to be loaded so `+load` fires and the
+      //      module is registered before JS calls `__turboModuleProxy`.
+      //      Same convention upstream RN's iOS Podfile relies on.
+      // -------------------------------------------------------------
+      const targetBuildConfigListId = /** @type {any} */ (target)
+        .buildConfigurationList;
+      const configList = /** @type {any} */ (
+        objects.XCConfigurationList[targetBuildConfigListId]
+      );
+      for (const ref of configList.buildConfigurations || []) {
+        const cfg = /** @type {any} */ (
+          objects.XCBuildConfiguration[ref.value]
+        );
+        cfg.buildSettings = cfg.buildSettings || {};
+        cfg.buildSettings['"EXCLUDED_ARCHS[sdk=watchsimulator*]"'] = 'x86_64';
+        let ldflags = cfg.buildSettings['OTHER_LDFLAGS'];
+        ldflags = mergeLdflags(ldflags, '-lc++');
+        ldflags = mergeLdflags(ldflags, '-ObjC');
+        cfg.buildSettings['OTHER_LDFLAGS'] = ldflags;
+      }
+
+      // -------------------------------------------------------------
+      // Write the modified pbxproj back to disk
+      // -------------------------------------------------------------
+      fs.writeFileSync(pbxprojPath, project.writeSync());
+
+      return cfg;
+    },
+  ]);
+};
+
+function findPbxproj(platformRoot) {
+  const xcodeproj = fs
+    .readdirSync(platformRoot)
+    .find((name) => name.endsWith('.xcodeproj'));
+  if (!xcodeproj) {
+    throw new Error(
+      `[@appsent-co/react-native-watchos] No .xcodeproj found in ${platformRoot}`
+    );
+  }
+  return path.join(platformRoot, xcodeproj, 'project.pbxproj');
+}
+
+/**
+ * Append `flag` to an existing OTHER_LDFLAGS value (string or array, possibly
+ * quoted, possibly containing $(inherited)) without producing duplicates.
+ *
+ * @param {unknown} existing
+ * @param {string} flag
+ */
+function mergeLdflags(existing, flag) {
+  if (existing == null) {
+    return `"$(inherited) ${flag}"`;
+  }
+  if (Array.isArray(existing)) {
+    if (existing.some((v) => stripQuotes(v) === flag)) return existing;
+    return [...existing, `"${flag}"`];
+  }
+  const unquoted = stripQuotes(existing);
+  if (unquoted.split(/\s+/).includes(flag)) return existing;
+  return `"${unquoted} ${flag}"`;
+}
+
+function stripQuotes(s) {
+  if (typeof s !== 'string') return s;
+  if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+module.exports = withSPMPackage;