Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions .github/actions/setup/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,8 +26,25 @@ runs:
fi
shell: bash

# Dawn comes with the react-native-webgpu-dawn dependency; this only checks
# it against the C++ workarounds pinned to a Dawn commit.
# Cache only the pinned header ZIP. Apple SDK archives stay in the runner's
# shared local cache; this avoids uploading them in every setup job.
# Header copying verifies the cached ZIP, including when Yarn install is skipped.
- name: Cache Dawn header archive
uses: actions/cache@v4
with:
path: |
~/Library/Caches/react-native-skia/*/*/dawn-headers.zip
~/.cache/react-native-skia/*/*/dawn-headers.zip
~/AppData/Local/react-native-skia/*/*/dawn-headers.zip
key: ${{ runner.os }}-${{ runner.arch }}-dawn-headers-${{ hashFiles('packages/webgpu/binaries.json') }}

# Populate cpp/dawn/include before checks, compilation, and npm publishing.
# Checkout omits these source/generated headers; no native build runs here.
- name: Copy Dawn headers
working-directory: packages/webgpu
shell: bash
run: yarn copy-dawn-headers

- name: Check Dawn
working-directory: packages/webgpu
shell: bash
Expand Down
20 changes: 12 additions & 8 deletions .github/workflows/apple-sdks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,21 +8,25 @@ on:
- "packages/webgpu/apple/**"
- "packages/webgpu/cpp/**"
- "packages/webgpu/package.json"
- "packages/webgpu/binaries.json"
- "packages/webgpu/scripts/*apple*binaries.sh"
- "packages/webgpu/scripts/apple-binaries-utils.sh"
- "packages/webgpu/scripts/check-apple-sdks.sh"
- "packages/webgpu/scripts/prepare-dawn-headers.mjs"
- ".github/workflows/apple-sdks.yml"
jobs:
apple-sdks:
# Syntax-check only: no yarn install, no pods, no simulator. Only the Dawn
# headers are downloaded (about 1 MB out of the package's tarball).
# headers archive is downloaded from the pinned Skia binaries release.
runs-on: macos-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- name: Download Dawn headers
run: |
VERSION=$(node -p 'require("./packages/webgpu/package.json").dependencies["react-native-webgpu-dawn"]')
mkdir -p "$RUNNER_TEMP/dawn"
curl -sfL "https://registry.npmjs.org/react-native-webgpu-dawn/-/react-native-webgpu-dawn-$VERSION.tgz" \
| tar xz -C "$RUNNER_TEMP/dawn" package/include
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version-file: .nvmrc
- name: Prepare Dawn headers
run: node packages/webgpu/scripts/prepare-dawn-headers.mjs
- name: Check Apple sources against every SDK
run: packages/webgpu/scripts/check-apple-sdks.sh "$RUNNER_TEMP/dawn/package/include"
run: packages/webgpu/scripts/check-apple-sdks.sh
23 changes: 10 additions & 13 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -201,8 +201,8 @@ jobs:
# packages/webgpu/Package.swift resolves and compiles, so a pull request
# pays for it only when its diff touches what can change the outcome: the
# manifest and the autolinking config, the Apple and C++ sources it
# compiles, the scripts behind the Dawn check, the dependencies that pin
# react-native-webgpu-dawn, the example that links it, or CI itself. Pushes
# compiles, preparation/check scripts, the Dawn release pin,
# the example that links it, or CI itself. Pushes
# to main, the merge queue and manual runs always build SwiftPM. macOS builds
# on main, manual runs and relevant PRs; shared JavaScript is checked by
# bundle-macos on every PR.
Expand Down Expand Up @@ -237,7 +237,7 @@ jobs:
macos=false
while IFS= read -r file; do
case "$file" in
packages/webgpu/Package.swift|packages/webgpu/package.json|packages/webgpu/react-native.config.js|\
packages/webgpu/Package.swift|packages/webgpu/*.podspec|packages/webgpu/package.json|packages/webgpu/binaries.json|packages/webgpu/react-native.config.js|\
packages/webgpu/apple/*|packages/webgpu/cpp/*|packages/webgpu/scripts/*|\
spm-example/*|package.json|yarn.lock|\
.github/workflows/ci.yml|.github/actions/setup/*)
Expand All @@ -246,7 +246,7 @@ jobs:
;;
esac
case "$file" in
apps/example-macos/*|packages/webgpu/*.podspec|packages/webgpu/package.json|\
apps/example-macos/*|packages/webgpu/*.podspec|packages/webgpu/package.json|packages/webgpu/binaries.json|\
packages/webgpu/react-native.config.js|packages/webgpu/apple/*|packages/webgpu/cpp/*|\
packages/webgpu/scripts/*|package.json|yarn.lock|.yarn/patches/*|turbo.json|\
.github/workflows/ci.yml|.github/actions/setup/*)
Expand Down Expand Up @@ -292,15 +292,15 @@ jobs:

# The SwiftPM example gets its own job on a GitHub-hosted Mac. It needs no
# Metro, simulator or CocoaPods, so nothing ties it to the self-hosted
# machine, and a fresh runner is the strictest check that the WebGPUDawn
# binaryTarget resolves from the release zip + checksum with nothing cached.
# machine. The Xcode phase selects the simulator SDK archive and verifies
# its checksum, independently of SwiftPM package resolution.
# It used to be a step of `build`: a hung xcodebuild there blocked the iOS
# e2e result and held the self-hosted runner, which has no slack for that.
build-spm-ios:
needs: changes
if: needs.changes.outputs.spm == 'true'
runs-on: macos-latest
# Cold run: yarn install, Dawn download, RN artifacts, then one xcodebuild.
# Install JS/headers, resolve RN artifacts, then prepare Dawn during Xcode.
timeout-minutes: 25
steps:
- name: Checkout
Expand All @@ -320,7 +320,7 @@ jobs:

# spm-example sits outside the yarn workspace so its React Native can
# differ from the one apps/example pins: SwiftPM autolinking needs
# React Native 0.87+. It ships no lockfile; react and react-native are
# React Native 0.87.1+. It ships no lockfile; react and react-native are
# pinned exactly in its package.json.
- name: Install spm-example dependencies
working-directory: spm-example
Expand All @@ -333,11 +333,8 @@ jobs:
working-directory: spm-example/ios
run: npx react-native spm update

# No CocoaPods and no -disableAutomaticPackageResolution here (unlike
# the example app build above): react-native-webgpu is linked through
# its own Package.swift, and its WebGPUDawn binaryTarget resolves to a
# remote release zip + checksum with nothing cached ahead of time: this
# build's whole point is exercising that download-and-verify step.
# No CocoaPods: the package compiles from bundled headers, and its Xcode
# phase prepares only the selected SDK's Dawn before the app links.
- name: Build spm-example for iOS
working-directory: spm-example/ios
run: |
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -71,3 +71,7 @@ apps/vendor/
Package.resolved

.turbo

# Prepared release inputs and local Apple SDK overrides
packages/webgpu/cpp/dawn/include/
packages/webgpu/libs/
23 changes: 17 additions & 6 deletions apps/docs/content/docs/getting-started/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,17 @@ npm i react-native-webgpu

An Android app with a lower `minSdkVersion` fails to build; on Expo, the [config plugin](/docs/getting-started/expo#config-plugin) raises it for you.

## Prebuilt binaries

Both platforms use the [React Native Skia binaries release](https://github.com/wcandillon/react-native-skia/releases) pinned by this package's `binaries.json`:

- **Android:** Gradle downloads only the ABIs being built and caches them as Gradle dependencies.
- **Apple:**
- **CocoaPods:** `pod install` registers an Xcode phase; it downloads only the selected SDK's Dawn archive during compilation.
- **SwiftPM (optional):** The autolinking plugin registers the same phase. Package resolution uses bundled headers and a local link-settings package, without downloading Dawn.

Apple archives share Skia's `~/Library/Caches/react-native-skia` cache; set `RNSKIA_CACHE_DIR` to override it.

## Setup

Once installed, the global `navigator.gpu` API is available, the same entry point as in Chrome or Safari:
Expand Down Expand Up @@ -63,16 +74,16 @@ This replaces the package with a JS-only stand-in: `<Canvas>` renders as a plain

By default, `react-native-webgpu` links on iOS/macOS through CocoaPods autolinking, with no extra setup. The long-term plan is to move the Apple platforms to Swift Package Manager. It is available today as an alternative: the package also ships a `Package.swift` for React Native's SwiftPM autolinking, which needs no CocoaPods at all:

1. Use **React Native 0.87 or newer**. Earlier releases have no SwiftPM autolinking, so keep CocoaPods there.
1. Use **React Native 0.87.1 or newer**, with the autolinking plugin's `scriptPhases` hook. Keep CocoaPods on earlier releases.
2. From your app's `ios` directory, run `npx react-native spm add --deintegrate` once. It removes CocoaPods from the project and adds the Swift packages to the `.xcodeproj`. Then build the project (not a workspace) as usual.
3. Do not run `pod install` in that app: it would re-integrate CocoaPods and break the Swift packages.

Dawn comes as a prebuilt binary that Xcode downloads the first time it resolves packages.
Set **User Script Sandboxing** to **NO** on the app target. The Xcode phase needs access to the shared cache and build products. After upgrading the package, run `npx react-native spm update` again.

With React Native Skia v3 installed alongside, package resolution checks that both packages link the same Dawn release, and fails if they are not at [compatible versions](/docs/integrations/react-native-skia#compatibility). After changing either version, reset the package caches in Xcode (File > Packages > Reset Package Caches) if the error persists.
With a compatible React Native Skia integration installed, WebGPU supplies the single Dawn copy. Both packages must pin the same release version and Dawn commit; mismatches fail before linking. See [compatible versions](/docs/integrations/react-native-skia#compatibility).

<Callout type="warn" title="Platform coverage">
The Swift package targets iOS only: tvOS, macOS and Android still require the CocoaPods/Gradle autolinked path. See `spm-example` at the root of the [React Native WebGPU repo](https://github.com/wcandillon/react-native-webgpu) for a working reference project, and its README for the gotchas (stale `Package.resolved`, the stub `Podfile`).
The Swift package targets iOS only: tvOS, macOS and Android still require the CocoaPods/Gradle autolinked path. See `spm-example` at the root of the [React Native WebGPU repo](https://github.com/wcandillon/react-native-webgpu) for a working reference project, and its README for setup notes and the stub `Podfile`.
</Callout>

## Troubleshooting
Expand Down Expand Up @@ -101,8 +112,8 @@ The simulator's Metal stack is not identical to real hardware, and validation ca
Learn more in [Apple's documentation on validating Metal API usage](https://developer.apple.com/documentation/xcode/validating-your-apps-metal-api-usage/).
</Callout>

<Callout type="info" title="Android builds without network access">
Gradle downloads the prebuilt Dawn from the [GitHub releases of React Native Skia](https://github.com/wcandillon/react-native-skia/releases), which builds it, the first time it builds, only for the architectures being built, and caches it like any other Gradle dependency. To download it from a mirror or a local directory instead, set the `reactNativeSkiaBinariesUrl` Gradle property (or the `REACT_NATIVE_SKIA_BINARIES_URL` environment variable) to a URL or a `file:///` directory that holds the release assets under `binaries-<version>/`.
<Callout type="info" title="Builds without network access">
To use a mirror or local release directory on either platform, set `REACT_NATIVE_SKIA_BINARIES_URL` to a URL or `file:///` path holding `binaries-<version>/<asset>`. Android also accepts the `reactNativeSkiaBinariesUrl` Gradle property.
</Callout>

## Next steps
Expand Down
2 changes: 1 addition & 1 deletion apps/docs/content/docs/integrations/react-native-skia.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Because the two packages share Dawn, React Native Skia v3 and React Native WebGP
| 0.12.1 | 3.0.6 to 3.0.8, or 3.1.0 and later |
| 0.10.0 to 0.11.2 | 3.0.0 to 3.0.5 |

If the versions don't match, the native build fails with a `Dawn version mismatch` error rather than misbehaving at runtime. Both packages get Dawn from the `react-native-webgpu-dawn` npm package: make sure a single version of it is installed (`npm ls react-native-webgpu-dawn`, or `yarn why react-native-webgpu-dawn`).
For SDK-archive integration, both packages must pin the same release version and `dawn.commit` in `binaries.json`. WebGPU supplies Dawn; Skia must use its compatible external-Dawn integration so the app links one copy. A mismatch fails with `Dawn version mismatch`. The older binary-npm integrations follow their release-specific installation instructions.

The Graphite previews of v2 (`@shopify/react-native-skia@next`) follow the same rule. Regular v2 releases don't use Dawn, so they work alongside any version of React Native WebGPU.

Expand Down
1 change: 0 additions & 1 deletion apps/docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@
"eslint": "9.35.0",
"fumadocs-twoslash": "^3.2.0",
"fumadocs-typescript": "^4.0.4",
"react-native-skia": "3.10.0",
"react-native-vision-camera": "5.0.10",
"tailwindcss": "^4.1.8",
"twoslash": "^0.3.9",
Expand Down
4 changes: 2 additions & 2 deletions apps/example-macos/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ yarn workspace example-macos pod:install:macos
yarn workspace example-macos build:macos
```

The app targets macOS 14.0. Dawn comes from `react-native-webgpu-dawn`; nothing
is built from Dawn sources. For development, run these in separate terminals:
The app targets macOS 14.0. Dawn is prepared from the pinned SDK archive during Xcode compilation;
nothing is built from Dawn sources. For development, run these in separate terminals:

```sh
yarn workspace example-macos start
Expand Down
36 changes: 1 addition & 35 deletions apps/example-macos/macos/Podfile.lock
Original file line number Diff line number Diff line change
Expand Up @@ -2021,36 +2021,6 @@ PODS:
- ReactCommon/turbomodule/core
- SocketRocket
- Yoga
- react-native-skia (3.10.0):
- boost
- DoubleConversion
- fast_float
- fmt
- glog
- hermes-engine
- RCT-Folly
- RCT-Folly/Fabric
- RCTRequired
- RCTTypeSafety
- React
- React-callinvoker
- React-Core
- React-debug
- React-Fabric
- React-featureflags
- React-graphics
- React-ImageManager
- React-jsi
- React-NativeModulesApple
- React-RCTFabric
- React-renderercss
- React-rendererdebug
- React-utils
- ReactCodegen
- ReactCommon/turbomodule/bridging
- ReactCommon/turbomodule/core
- SocketRocket
- Yoga
- react-native-webgpu (0.0.0):
- boost
- DoubleConversion
Expand Down Expand Up @@ -2965,7 +2935,6 @@ DEPENDENCIES:
- React-microtasksnativemodule (from `../node_modules/react-native-macos/ReactCommon/react/nativemodule/microtasks`)
- React-mutationobservernativemodule (from `../node_modules/react-native-macos/ReactCommon/react/nativemodule/mutationobserver`)
- react-native-safe-area-context (from `../node_modules/react-native-safe-area-context`)
- react-native-skia (from `../node_modules/react-native-skia`)
- react-native-webgpu (from `../node_modules/react-native-webgpu`)
- React-NativeModulesApple (from `../node_modules/react-native-macos/ReactCommon/react/nativemodule/core/platform/ios`)
- React-networking (from `../node_modules/react-native-macos/ReactCommon/react/networking`)
Expand Down Expand Up @@ -3106,8 +3075,6 @@ EXTERNAL SOURCES:
:path: "../node_modules/react-native-macos/ReactCommon/react/nativemodule/mutationobserver"
react-native-safe-area-context:
:path: "../node_modules/react-native-safe-area-context"
react-native-skia:
:path: "../node_modules/react-native-skia"
react-native-webgpu:
:path: "../node_modules/react-native-webgpu"
React-NativeModulesApple:
Expand Down Expand Up @@ -3239,8 +3206,7 @@ SPEC CHECKSUMS:
React-microtasksnativemodule: 19a679c33c2a30339ded09015f3b150d17741dd9
React-mutationobservernativemodule: fd162222cbf7aa9f00ceaddcfcf3af472dd84db0
react-native-safe-area-context: 6cf08f4151132f9cf2adb948dc6c4ac387f8d30f
react-native-skia: 2a2e368f129a7c029b5dd22e06395eac4fe94c3f
react-native-webgpu: a038711df350957d325a322211216bb73dac7a10
react-native-webgpu: 7f9b1b83788339356f7567add013bef85f1cf117
React-NativeModulesApple: 5ead5f7c62cdc951f5090c3f736f4da36c1807b5
React-networking: d61cd2aed6bd3ef10baef7b327219f7c12a6969b
React-oscompat: 7551cbe14bc1ff01314e9cf119a985abe3e70344
Expand Down
1 change: 0 additions & 1 deletion apps/example-macos/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,6 @@
"react-native-reanimated": "4.6.0",
"react-native-safe-area-context": "^5.4.0",
"react-native-screens": "4.19.0",
"react-native-skia": "3.10.0",
"react-native-webgpu": "workspace:*",
"react-native-worklets": "0.12.2",
"teapot": "^1.0.0",
Expand Down
31 changes: 1 addition & 30 deletions apps/example/ios/Podfile.lock
Original file line number Diff line number Diff line change
Expand Up @@ -1470,31 +1470,6 @@ PODS:
- ReactCommon/turbomodule/core
- ReactNativeDependencies
- Yoga
- react-native-skia (3.10.0):
- hermes-engine
- RCTRequired
- RCTTypeSafety
- React
- React-bridging
- React-callinvoker
- React-Core
- React-Core-prebuilt
- React-cxxstableapi
- React-debug
- React-Fabric
- React-featureflags
- React-graphics
- React-ImageManager
- React-jsi
- React-NativeModulesApple
- React-RCTFabric
- React-renderercss
- React-rendererdebug
- React-utils
- ReactCodegen
- ReactCommon/turbomodule/core
- ReactNativeDependencies
- Yoga
- react-native-webgpu (0.0.0):
- hermes-engine
- RCTRequired
Expand Down Expand Up @@ -2298,7 +2273,6 @@ DEPENDENCIES:
- React-microtasksnativemodule (from `../../../node_modules/react-native/ReactCommon/react/nativemodule/microtasks`)
- React-mutationobservernativemodule (from `../../../node_modules/react-native/ReactCommon/react/nativemodule/mutationobserver`)
- react-native-safe-area-context (from `../../../node_modules/react-native-safe-area-context`)
- react-native-skia (from `../../../node_modules/react-native-skia`)
- react-native-webgpu (from `../../../node_modules/react-native-webgpu`)
- React-NativeModulesApple (from `../../../node_modules/react-native/ReactCommon/react/nativemodule/core/platform/ios`)
- React-networking (from `../../../node_modules/react-native/ReactCommon/react/networking`)
Expand Down Expand Up @@ -2451,8 +2425,6 @@ EXTERNAL SOURCES:
:path: "../../../node_modules/react-native/ReactCommon/react/nativemodule/mutationobserver"
react-native-safe-area-context:
:path: "../../../node_modules/react-native-safe-area-context"
react-native-skia:
:path: "../../../node_modules/react-native-skia"
react-native-webgpu:
:path: "../../../node_modules/react-native-webgpu"
React-NativeModulesApple:
Expand Down Expand Up @@ -2603,8 +2575,7 @@ SPEC CHECKSUMS:
React-microtasksnativemodule: 0207d6133274a7cbfc3d0dae326e3055c8cfcf9e
React-mutationobservernativemodule: b97a67c29f724d18a92379e7390f24350acb433a
react-native-safe-area-context: 949375a80dca43886b96574e6c97a0c5b37a479c
react-native-skia: 8bc263ce99daef1d357c65681e5085b1d3d95157
react-native-webgpu: 27abd5e7a0af033bc91767a338cea31f441f58af
react-native-webgpu: 8999dd037f25c37339f8fafa937855561f322f5a
React-NativeModulesApple: 8cfb2f308f48c48068c96b932e7f0e4297c23342
React-networking: 3325cf73ecbdaacab0da91260b094baf36061a56
React-oscompat: a776760fdfa152e12114f8c30d833963daac27e1
Expand Down
1 change: 0 additions & 1 deletion apps/example/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,6 @@
"react-native-reanimated": "4.7.1",
"react-native-safe-area-context": "^5.4.0",
"react-native-screens": "^4.30.1",
"react-native-skia": "3.10.0",
"react-native-vision-camera": "5.0.10",
"react-native-vision-camera-worklets": "5.0.10",
"react-native-web": "^0.21.2",
Expand Down
Loading