fix(⚛️): ship an Expo config plugin that disables Metal API validation (#412)

wcandillon · web-flow · commit bcec155f8b17 · 2026-07-08T18:18:51.000+02:00
Running WebGPU on the iOS Simulator requires disabling Metal API validation: Dawn triggers false-positive validation errors that do not occur on device. With Expo's Continuous Native Generation, unchecking the setting manually in Xcode does not survive `expo prebuild --clean`, so a config plugin has to re-apply it on every prebuild. Following Expo's guidance that packages should ship their own config plugin (so plugin and package versions stay aligned), the plugin lives in this package rather than in expo/config-plugins. Usage: { "expo": { "plugins": ["react-native-webgpu"] } } The plugin sets enableGPUValidationMode="1" on the LaunchAction of all shared Xcode schemes of the iOS project - the same mechanism Flutter uses (flutter/flutter#159228) and the equivalent of unchecking Product > Scheme > Edit Scheme > Run > Diagnostics > Metal API Validation. - plugin/src is compiled to plugin/build by `yarn build:plugin`, which is part of `yarn build`, so the existing release workflow (publish-npm.yml) ships the plugin with every package release - app.plugin.js is the entry point Expo resolves; it and plugin/build are added to the published files - unit tests (yarn test:plugin) run standalone from the e2e harness and are wired into CI - documented in the docs app (Expo guide + installation troubleshooting), the package README, and CONTRIBUTING.md
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -52,6 +52,10 @@ jobs:
       - name: Build packages
         run: yarn turbo run build --filter='./packages/*'
 
+      - name: Test Expo config plugin
+        working-directory: packages/webgpu
+        run: yarn test:plugin
+
       # Validate the semantic-release config without publishing, so a broken
       # .releaserc or publish script is caught on PRs rather than at release time.
       - name: Release dry run
diff --git a/apps/docs/content/docs/getting-started/expo.mdx b/apps/docs/content/docs/getting-started/expo.mdx
@@ -16,3 +16,21 @@ The template includes `react-native-webgpu`, Reanimated, and Metro settings comp
 For a walkthrough of the template, watch the video below.
 
 <Video src="/videos/expo-template.mp4" />
+
+## Config plugin
+
+`react-native-webgpu` ships its own [Expo config plugin](https://docs.expo.dev/config-plugins/introduction/). Add it to the `plugins` array of your app config:
+
+```json title="app.json"
+{
+  "expo": {
+    "plugins": ["react-native-webgpu"]
+  }
+}
+```
+
+The plugin disables **Metal API Validation** in the shared Xcode scheme of your iOS project - the equivalent of unchecking Product → Scheme → Edit Scheme → Run → Diagnostics → Metal API Validation in Xcode. This is required to run WebGPU on the **iOS Simulator**: Metal API validation flags false positives in Dawn that do not occur on a physical device and would otherwise crash the app (see the [troubleshooting section](/docs/getting-started/installation#troubleshooting)).
+
+With [Continuous Native Generation](https://docs.expo.dev/workflow/continuous-native-generation/), the `ios` directory is regenerated by `npx expo prebuild --clean`, so unchecking the setting manually in Xcode does not stick - the config plugin re-applies it on every prebuild.
+
+The plugin only affects the iOS Xcode scheme; it is a no-op on Android and it changes nothing for release builds on physical devices. Since the plugin ships with the package, its version is always aligned with the `react-native-webgpu` version you have installed.
diff --git a/apps/docs/content/docs/getting-started/installation.mdx b/apps/docs/content/docs/getting-started/installation.mdx
@@ -48,7 +48,17 @@ On Android emulators, WebGPU may fall back to a **software adapter**. Rendering
 <Callout type="warn" title="iOS Simulator - Metal API Validation">
 When running on the **iOS Simulator**, disable **Metal API Validation** in Xcode or you may hit false-positive errors and crashes that do not occur on device.
 
-**Steps:** Product → Scheme → Edit Scheme → Run → Diagnostics → uncheck **Metal API Validation**.
+**Expo:** add the [config plugin](/docs/getting-started/expo#config-plugin) that ships with `react-native-webgpu` to your app config - it disables the setting automatically on every prebuild:
+
+```json title="app.json"
+{
+  "expo": {
+    "plugins": ["react-native-webgpu"]
+  }
+}
+```
+
+**Bare React Native:** Product → Scheme → Edit Scheme → Run → Diagnostics → uncheck **Metal API Validation**.
 
 Metal API Validation is a debug mode that checks every Metal call against the API specification. The simulator's Metal stack is not identical to real hardware, and validation can flag legitimate Dawn/WebGPU usage as invalid. Disabling it for local development is standard practice; keep validation enabled when debugging raw Metal code on device if needed.
 
diff --git a/packages/webgpu/.gitignore b/packages/webgpu/.gitignore
@@ -71,3 +71,6 @@ android/keystores/debug.keystore
 
 # generated by bob
 lib/
+
+# compiled Expo config plugin
+plugin/build/
diff --git a/packages/webgpu/CONTRIBUTING.md b/packages/webgpu/CONTRIBUTING.md
@@ -13,10 +13,14 @@ Example app (from `apps/example/`): `yarn start` · `yarn ios` · `yarn android`
 
 From the repo root: `yarn lint` · `yarn tsc` · `yarn build:docs`
 
-Tests (from `packages/webgpu/`): `yarn test:ref` (Chrome reference) · `yarn test` (E2E — open the example app on the E2E screen)
+Tests (from `packages/webgpu/`): `yarn test:ref` (Chrome reference) · `yarn test` (E2E — open the example app on the E2E screen) · `yarn test:plugin` (Expo config plugin unit tests)
 
 Other `packages/webgpu` scripts: `yarn codegen` · `yarn clean-dawn` · `yarn build-dawn`
 
+## Expo config plugin
+
+The Expo config plugin lives in `plugin/src` and is compiled to `plugin/build` by `yarn build:plugin` (also part of `yarn build`, so releases always ship it). `app.plugin.js` at the package root is the entry point Expo resolves when apps list `"react-native-webgpu"` in their `plugins`. The plugin disables Metal API validation in the generated iOS Xcode scheme (required on the iOS Simulator); it is released together with the package by the regular release workflow, so plugin and package versions are always aligned.
+
 ## Upgrading Dawn
 
 The Dawn version is pinned in two places that must stay in sync:
diff --git a/packages/webgpu/README.md b/packages/webgpu/README.md
@@ -8,6 +8,20 @@ WebGPU for React Native, powered by Dawn.
 
 [Installation instructions](https://wcandillon.github.io/react-native-webgpu/docs/getting-started/installation)
 
+## Expo config plugin
+
+The package ships with an Expo config plugin that disables Metal API validation in the iOS Xcode scheme, which is required to run WebGPU on the iOS Simulator (Metal API validation reports false positives for Dawn that do not occur on device). Because the plugin is part of the package, plugin and package versions are always aligned.
+
+```json
+{
+  "expo": {
+    "plugins": ["react-native-webgpu"]
+  }
+}
+```
+
+See the [Expo guide](https://wcandillon.github.io/react-native-webgpu/docs/getting-started/expo#config-plugin) for details.
+
 ## Contributing
 
 For detailed information on library development, building, testing, and contributing guidelines, please see [CONTRIBUTING.md](packages/webgpu/CONTRIBUTING.md).
diff --git a/packages/webgpu/app.plugin.js b/packages/webgpu/app.plugin.js
@@ -0,0 +1 @@
+module.exports = require("./plugin/build").default;
diff --git a/packages/webgpu/eslint.config.mjs b/packages/webgpu/eslint.config.mjs
@@ -3,7 +3,7 @@ import wcandillon from "eslint-config-react-native-wcandillon";
 
 export default [
   {
-    ignores: ["**/*/components/meshes", "node_modules/**", "lib/**", "android/**", "ios/**", "*.config.js"]
+    ignores: ["**/*/components/meshes", "node_modules/**", "lib/**", "android/**", "ios/**", "*.config.js", "plugin/build/**", "plugin/jest.config.js", "app.plugin.js"]
   },
   ...wcandillon,
   {
diff --git a/packages/webgpu/jest.config.js b/packages/webgpu/jest.config.js
@@ -11,7 +11,10 @@ module.exports = {
   // modulePathIgnorePatterns only affects the module registry, not test
   // discovery. Without this, the .d.ts files emitted into lib/ by `bob build`
   // are picked up as test suites and fail with "must contain at least one test".
-  testPathIgnorePatterns: ['/node_modules/', '<rootDir>/lib/'],
+  // The Expo config plugin has its own standalone jest config
+  // (plugin/jest.config.js, run via `yarn test:plugin`) so its unit tests do
+  // not go through the e2e globalSetup below.
+  testPathIgnorePatterns: ['/node_modules/', '<rootDir>/lib/', '<rootDir>/plugin/'],
   globalSetup: './src/__tests__/globalSetup.ts',
   globalTeardown: './src/__tests__/globalTeardown.ts',
   transform: {
diff --git a/packages/webgpu/package.json b/packages/webgpu/package.json
@@ -18,15 +18,19 @@
     "cpp/**/*.{h,cpp}",
     "apple/**",
     "libs/**",
-    "*.podspec"
+    "*.podspec",
+    "app.plugin.js",
+    "plugin/build/**"
   ],
   "dawn": "chromium/7849",
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-require-module' jest -i",
     "test:ref": "REFERENCE=true NODE_OPTIONS='--experimental-require-module' jest -i",
+    "test:plugin": "jest -c plugin/jest.config.js",
     "lint": "eslint . --ext .ts,.tsx  --max-warnings 0 --cache --fix",
     "tsc": "tsc --noEmit",
-    "build": "bob build",
+    "build": "bob build && yarn build:plugin",
+    "build:plugin": "tsc -p plugin/tsconfig.build.json",
     "release": "semantic-release",
     "build-dawn": "tsx scripts/build/dawn.ts",
     "clean-dawn": "rimraf ./libs && rimraf ../../externals/dawn/out",
@@ -41,7 +45,9 @@
   "keywords": [
     "react-native",
     "ios",
-    "android"
+    "android",
+    "expo",
+    "expo-config-plugin"
   ],
   "repository": {
     "type": "git",
@@ -59,6 +65,7 @@
     "provenance": true
   },
   "devDependencies": {
+    "@expo/config-plugins": "^57.0.3",
     "@semantic-release/commit-analyzer": "^13.0.0",
     "@semantic-release/exec": "^7.0.3",
     "@semantic-release/github": "^10.3.3",
diff --git a/packages/webgpu/plugin/jest.config.js b/packages/webgpu/plugin/jest.config.js
@@ -0,0 +1,19 @@
+// Standalone config for the Expo config plugin unit tests. The package's main
+// jest config drives the e2e harness (it boots a WebSocket server and waits
+// for the example app), which the plugin tests must not depend on.
+module.exports = {
+  rootDir: __dirname,
+  testEnvironment: "node",
+  testMatch: ["<rootDir>/src/__tests__/**/*.test.ts"],
+  transform: {
+    "^.+\\.(js|ts)$": [
+      "babel-jest",
+      {
+        presets: [
+          [require.resolve("@babel/preset-env"), { targets: { node: "current" } }],
+          require.resolve("@babel/preset-typescript"),
+        ],
+      },
+    ],
+  },
+};
diff --git a/packages/webgpu/plugin/src/__tests__/setMetalApiValidation.test.ts b/packages/webgpu/plugin/src/__tests__/setMetalApiValidation.test.ts
@@ -0,0 +1,70 @@
+import { setMetalApiValidationDisabled } from "../setMetalApiValidation";
+
+// Trimmed-down version of the scheme generated by `npx expo prebuild`.
+const makeScheme = (
+  launchActionAttributes: string,
+) => `<?xml version="1.0" encoding="UTF-8"?>
+<Scheme
+   LastUpgradeVersion = "1130"
+   version = "1.3">
+   <BuildAction
+      parallelizeBuildables = "YES"
+      buildImplicitDependencies = "YES">
+   </BuildAction>
+   <LaunchAction
+      buildConfiguration = "Debug"
+      selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
+      selectedLauncherIdentifier = "Xcode.DebuggerFoundation.Launcher.LLDB"
+      launchStyle = "0"
+      useCustomWorkingDirectory = "NO"
+      ignoresPersistentStateOnLaunch = "NO"
+      debugDocumentVersioning = "YES"
+      debugServiceExtension = "internal"${launchActionAttributes}
+      allowLocationSimulation = "YES">
+      <BuildableProductRunnable
+         runnableDebuggingMode = "0">
+      </BuildableProductRunnable>
+   </LaunchAction>
+   <ProfileAction
+      buildConfiguration = "Release"
+      shouldUseLaunchSchemeArgsEnv = "YES">
+   </ProfileAction>
+</Scheme>
+`;
+
+describe("setMetalApiValidationDisabled", () => {
+  it("adds enableGPUValidationMode to a scheme without the attribute", () => {
+    const result = setMetalApiValidationDisabled(makeScheme(""));
+    expect(result).toContain('enableGPUValidationMode = "1"');
+    // The attribute must land on the LaunchAction element, not elsewhere.
+    const [launchAction] = result.match(/<LaunchAction[^>]*>/)!;
+    expect(launchAction).toContain('enableGPUValidationMode = "1"');
+  });
+
+  it("overwrites an existing enableGPUValidationMode value", () => {
+    const scheme = makeScheme('\n      enableGPUValidationMode = "2"');
+    const result = setMetalApiValidationDisabled(scheme);
+    expect(result).toContain('enableGPUValidationMode = "1"');
+    expect(result).not.toContain('enableGPUValidationMode = "2"');
+  });
+
+  it("is idempotent", () => {
+    const once = setMetalApiValidationDisabled(makeScheme(""));
+    const twice = setMetalApiValidationDisabled(once);
+    expect(twice).toBe(once);
+  });
+
+  it("produces a valid LaunchAction opening tag", () => {
+    const result = setMetalApiValidationDisabled(makeScheme(""));
+    const [launchAction] = result.match(/<LaunchAction[^>]*>/)!;
+    expect(launchAction.endsWith('enableGPUValidationMode = "1">')).toBe(true);
+    expect(launchAction).toContain('allowLocationSimulation = "YES"');
+    expect(result.match(/enableGPUValidationMode/g)).toHaveLength(1);
+  });
+
+  it("does not touch other actions", () => {
+    const result = setMetalApiValidationDisabled(makeScheme(""));
+    const [profileAction] = result.match(/<ProfileAction[^>]*>/)!;
+    expect(profileAction).not.toContain("enableGPUValidationMode");
+  });
+});
diff --git a/packages/webgpu/plugin/src/index.ts b/packages/webgpu/plugin/src/index.ts
@@ -0,0 +1,17 @@
+import { createRunOncePlugin } from "@expo/config-plugins";
+import type { ConfigPlugin } from "@expo/config-plugins";
+
+import { withMetalApiValidationDisabled } from "./withMetalApiValidation";
+
+const pkg = require("../../package.json") as {
+  name: string;
+  version: string;
+};
+
+const withWebGPU: ConfigPlugin = (config) =>
+  withMetalApiValidationDisabled(config);
+
+// Expo resolves config plugins through their default export (re-exported by
+// app.plugin.js at the package root).
+// eslint-disable-next-line import/no-default-export
+export default createRunOncePlugin(withWebGPU, pkg.name, pkg.version);
diff --git a/packages/webgpu/plugin/src/setMetalApiValidation.ts b/packages/webgpu/plugin/src/setMetalApiValidation.ts
@@ -0,0 +1,24 @@
+/**
+ * Rewrites an Xcode scheme (.xcscheme XML) so that Metal API validation is
+ * disabled for the Run action — the same effect as unchecking
+ * Product → Scheme → Edit Scheme → Run → Diagnostics → Metal API Validation.
+ *
+ * Xcode encodes the setting as the `enableGPUValidationMode` attribute on the
+ * <LaunchAction> element: the attribute is absent when validation is enabled
+ * (the default) and set to "1" when disabled. This mirrors how Flutter
+ * disables Metal API validation in its templates
+ * (https://github.com/flutter/flutter/pull/159228).
+ */
+export const setMetalApiValidationDisabled = (xcscheme: string): string =>
+  xcscheme.replace(
+    /<LaunchAction([^>]*)>/,
+    (launchAction, attributes: string) => {
+      if (attributes.includes("enableGPUValidationMode")) {
+        return launchAction.replace(
+          /enableGPUValidationMode\s*=\s*"[^"]*"/,
+          'enableGPUValidationMode = "1"',
+        );
+      }
+      return `<LaunchAction${attributes}\n      enableGPUValidationMode = "1">`;
+    },
+  );
diff --git a/packages/webgpu/plugin/src/withMetalApiValidation.ts b/packages/webgpu/plugin/src/withMetalApiValidation.ts
@@ -0,0 +1,46 @@
+import * as fs from "fs";
+import * as path from "path";
+
+import { withDangerousMod } from "@expo/config-plugins";
+import type { ConfigPlugin } from "@expo/config-plugins";
+
+import { setMetalApiValidationDisabled } from "./setMetalApiValidation";
+
+const getSharedSchemes = (platformProjectRoot: string): string[] => {
+  if (!fs.existsSync(platformProjectRoot)) {
+    return [];
+  }
+  return fs
+    .readdirSync(platformProjectRoot)
+    .filter((entry) => entry.endsWith(".xcodeproj"))
+    .map((entry) =>
+      path.join(platformProjectRoot, entry, "xcshareddata", "xcschemes"),
+    )
+    .filter((schemesDir) => fs.existsSync(schemesDir))
+    .flatMap((schemesDir) =>
+      fs
+        .readdirSync(schemesDir)
+        .filter((file) => file.endsWith(".xcscheme"))
+        .map((file) => path.join(schemesDir, file)),
+    );
+};
+
+/**
+ * Disables Metal API validation in every shared Xcode scheme of the iOS
+ * project. Dawn (the WebGPU implementation) triggers false-positive
+ * validation errors on the iOS Simulator that do not occur on device.
+ * Manually unchecking the setting in Xcode does not survive
+ * `npx expo prebuild --clean`, which is why this is a config plugin.
+ */
+export const withMetalApiValidationDisabled: ConfigPlugin = (config) =>
+  withDangerousMod(config, [
+    "ios",
+    async (cfg) => {
+      const schemes = getSharedSchemes(cfg.modRequest.platformProjectRoot);
+      for (const scheme of schemes) {
+        const contents = fs.readFileSync(scheme, "utf8");
+        fs.writeFileSync(scheme, setMetalApiValidationDisabled(contents));
+      }
+      return cfg;
+    },
+  ]);
diff --git a/packages/webgpu/plugin/tsconfig.build.json b/packages/webgpu/plugin/tsconfig.build.json
@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "outDir": "build",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "exclude": ["src/__tests__"]
+}
diff --git a/packages/webgpu/plugin/tsconfig.json b/packages/webgpu/plugin/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2019",
+    "lib": ["ES2019"],
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node", "jest"]
+  },
+  "include": ["src"]
+}
diff --git a/packages/webgpu/tsconfig.build.json b/packages/webgpu/tsconfig.build.json
@@ -1,6 +1,6 @@
 {
   "extends": "./tsconfig",
-  "exclude": ["scripts"],
+  "exclude": ["scripts", "plugin"],
   "compilerOptions": {
     "noEmit": false,
   }
diff --git a/turbo.json b/turbo.json
@@ -71,7 +71,7 @@
     "lint": {},
     "tsc": {},
     "build": {
-      "outputs": ["lib/**", ".next/**", "out/**"]
+      "outputs": ["lib/**", "plugin/build/**", ".next/**", "out/**"]
     },
     "build:docs": {
       "env": ["GITHUB_PAGES"],
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+module.exports = require("./plugin/build").default;`
Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,7 @@ import wcandillon from "eslint-config-react-native-wcandillon";`
`3`	`3`
`4`	`4`	`export default [`
`5`	`5`	`{`
`6`		`- ignores: ["*//components/meshes", "node_modules/", "lib/", "android/", "ios/", "*.config.js"]`
	`6`	`+ ignores: ["*//components/meshes", "node_modules/", "lib/", "android/", "ios/", ".config.js", "plugin/build/*", "plugin/jest.config.js", "app.plugin.js"]`
`7`	`7`	`},`
`8`	`8`	`...wcandillon,`
`9`	`9`	`{`