Skip to content

nitro-webview v0.2.0

Choose a tag to compare

@l2hyunwoo l2hyunwoo released this 10 Oct 14:37
· 9 commits to main since this release
f4f51a6

Nitro WebView 0.2.0

This release updates native navigation decisions, JavaScript evaluation, renderer recovery, downloads, and origin and permission controls.

Upgrading from 0.1.0

Rebuild and reinstall the native app after upgrading. A Metro reload or an over-the-air JavaScript update cannot replace the changed navigation callback bindings.
Use matching JavaScript, generated bindings, and native binaries.

npm install nitro-webview@0.2.0 react-native-nitro-modules
# Then reinstall iOS pods and rebuild both native apps.
  • React Native: ~0.85.3, with the New Architecture enabled.
  • React: exactly 19.2.3.
  • Nitro Modules: ^0.35.9; development runtime and Nitrogen generator: 0.35.9.
  • Android API 24+ and iOS 15.1+. Android renderer recovery requires API 26+.
  • Android and iOS only. Web, macOS, Windows, visionOS, and tvOS are unsupported.

These ranges define the support policy. They do not establish that every future version or device combination has passed native validation.

Compatibility changes

  • evaluateJavaScript() returns JSON text on both platforms. Apply JSON.parse() once. String values include JSON quotes; null and undefined return 'null'. Android can also return 'null' when it cannot distinguish a JavaScript exception from a null result.
  • Navigation callbacks still accept boolean | Promise<boolean> and require callback(...). Configure them through React props. Hybrid refs expose read-only methods and Nitro lifecycle APIs, not view props.
  • Android navigation decisions have a nominal 250 ms wait budget with an allow fallback on timeout, rejection, or interruption. This does not bound UI delay. Initial sources and POST requests bypass that platform hook. iOS waits for the Promise while the view remains active; stopLoading(), unmount, or content-process termination cancels pending decisions.
  • Origin helpers apply both the URL allowlist and the handler result, including default patterns. They do not filter all network requests or authenticate message senders.
  • Source headers override defaults case-insensitively. Duplicate logical header names within one input map fail validation. Android POST rejects nonempty custom headers.
  • Android renderer exit destroys the affected WebView. Clear its hybrid ref and remount with a new React key after an explicit retry. Old Promise methods reject with NitroWebViewState. Remounting loses history and input; do not automatically replay POST sources. iOS recovery continues to use reload().
  • iOS incognito, javaScriptEnabled, and sharedCookiesEnabled are initial settings. Remount to change them. Each private mount has its own ephemeral store. Shared cookies are imported once, not continuously synchronized. Android rejects incognito=true; its cookies remain process-wide. Clearing a shared cookie store affects other views in that store.
  • clearHistory() remains a successful no-op on iOS. Remount when a fresh history stack is required.
  • Android blob downloads allow one reader per view, up to 8 MiB, with a 30-second timeout. Download failures use NitroWebViewDownload errors without failing the page load. Move or delete successful iOS temporary files and their UUID directories after use.
  • Advanced parseBlobEnvelope(raw, pending) callers must pass { requestId, url, fileName } or undefined explicitly. Uncorrelated legacy envelopes no longer produce downloads.

Platform behavior to review

POST sources, load events, JavaScript dialogs, media playback, message-origin controls, and camera/microphone/location policies have native regression coverage.
Review platform differences before enabling them in your app:

  • Android camera, microphone, and location access is denied until exact origins are allowed and OS permissions are granted. iOS retains system website permission prompts.
  • Configured Android message-origin filtering requires System WebView WEB_MESSAGE_LISTENER support and fails closed when unsupported.
  • iOS media playback settings are initial-only. Android early script injection depends on installed WebView support and can use an early timing fallback.
  • File uploads need host-app permission configuration. HTTP(S) download events report metadata; the app remains responsible for downloading and saving bytes.

Read the migration guide, platform support, and 한국어 문서.

Release verification

  • Release source: f4f51a6.
  • The published tarball passes 37 Android regressions and 29 iOS core regressions. The iOS core profile runs in a Release app without Metro or XCTest UI automation. Four iOS OS UI scenarios remain in the separate full profile and are not covered by this release gate.
  • Android arm64 Release was checked on a physical device. An unsigned iOS device Release build passed; iOS physical-device execution was not checked.
  • Release workflow

Full changelog: v0.1.0...v0.2.0