Repository navigation
Releases
nitro-webview v0.2.2
Changes
NitroWebView now accepts plain functions for all 13 event props and hybridRef. Existing callback(fn) handlers remain supported.
<NitroWebView
source={{ uri: 'https://example.com' }}
onMessage={(event) => console.log(event.nativeEvent.data)}
/>The component reuses callback wrappers when the underlying function is unchanged and clears handlers when passed undefined. Async navigation decisions and event payloads retain their existing behavior. English and Korean guides now describe the 0.2.2 API.
Installation
yarn add nitro-webview@0.2.2 react-native-nitro-modules
# or
npm install nitro-webview@0.2.2 react-native-nitro-modulesPeer requirements remain React Native ~0.85.3 with the New Architecture, React 19.2.3, and Nitro Modules ^0.35.9.
nitro-webview v0.2.1
What's Changed
- chore(release): prepare v0.2.1 (#50)
- test(e2e): compare post-mount and steady-state WebView latency (#49)
- perf: avoid redundant WebView reloads and optimize message delivery (#48)
Installation
yarn add nitro-webview@0.2.1
# or
npm install nitro-webview@0.2.1Rebuild the native app after upgrading.
Documentation
Full Changelog: v0.2.0...v0.2.1
nitro-webview v0.2.0
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. ApplyJSON.parse()once. String values include JSON quotes;nullandundefinedreturn'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 requirecallback(...). 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
keyafter an explicit retry. Old Promise methods reject withNitroWebViewState. Remounting loses history and input; do not automatically replay POST sources. iOS recovery continues to usereload(). - iOS
incognito,javaScriptEnabled, andsharedCookiesEnabledare initial settings. Remount to change them. Each private mount has its own ephemeral store. Shared cookies are imported once, not continuously synchronized. Android rejectsincognito=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
NitroWebViewDownloaderrors 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 }orundefinedexplicitly. 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_LISTENERsupport 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
nitro-webview v0.1.0
What's Changed
- ci(release): fix SIGPIPE exit 141 by replacing head pipe with --max-count
- ci(release): bump Node.js to 22 for --experimental-strip-types support
- ci(release): add git-log release notes with full changelog link
- ci: add 4-job GitHub Actions release workflow
- docs(readme): rewrite with intro, quick start, and full API reference
- refactor(ios): update namespace references in Bridge.h and podspec
- refactor(android): migrate package identifier to io.github.l2hyunwoo.nitro.webview
- chore(package): bump version to 0.1.0 and update author/repo metadata
- chore(release): add MIT LICENSE file
- fix(example): start FileDownloadDemo on blank page instead of PDF URL
- fix(example): resolve three native runtime issues found in smoke test
- fix(example): handle Android back press and make controls scrollable
- refactor(example): modularize App.tsx into per-panel home-list router
- docs(readme): rewrite as a usage guide instead of a template README
- fix(example): drive navigation demo through user-initiated link taps
- feat(example): add navigation interception demo panel
- fix(src): strip orchestration-vocab from originWhitelist doc + tests
- fix(android): replace orchestration-vocab region markers in shouldStart test
- chore(tooling): add git pre-commit hook reusing the guardrail script
- chore(tooling): refine guardrail script to avoid URL-literal false positives
- test(android): add JUnit coverage for shouldOverrideUrlLoading
- test(ios): add XCTest probes for navigation interception
- feat(src): add originWhitelist helper for the navigation hook
- feat(android): wire onShouldStartLoadWithRequest through WebViewClient
- feat(ios): wire onShouldStartLoadWithRequest through WKNavigationDelegate
- chore(codegen): regenerate Nitrogen output for the navigation hook
- feat(spec): add onShouldStartLoadWithRequest navigation hook
- chore(tooling): add CLAUDE.md style guardrail hook script
- chore(git): track .claude/settings.json so guardrails ship with the repo
- feat(example): add User-Agent demo panel
- feat(android): wire userAgent setter onto WebSettings.userAgentString
- feat(ios): wire userAgent setter onto WKWebView.customUserAgent
- chore(codegen): regenerate Nitrogen output for the userAgent prop
- feat(spec): add userAgent prop to NitroWebViewProps
- chore(git): untrack CLAUDE.md and fix the gitignore typo that masked it
- test(spec): add Jest contract tests for the new spec surfaces
- feat(src): add JS-side headerMerge helper
- docs(readme): document iOS Info.plist keys for file upload
- feat(example): add demos for headers, cookies, file upload, file download
- chore(example): grant Android media permissions and expose Mozilla maven
- chore(example): declare iOS usage descriptions and file-access privacy keys
- test(android): add JUnit coverage for companion helpers and chrome client
- feat(android): add NitroWebChromeClient for file-upload chooser
- feat(android): implement headers, cookies, and file-download on WebView
- test(ios): add XCTest probes for the new feature surfaces
- feat(ios): implement headers, cookies, and file-download on WKWebView
- chore(codegen): regenerate Nitrogen output for the new spec surfaces
- feat(spec): add headers, cookies, and file-download surfaces
- chore(eslint): ignore Gradle test-report artifacts under android/build
- docs(claude): add platform-specific style guardrails and commit convention
Installation
yarn add nitro-webview@0.1.0
# or
npm install nitro-webview@0.1.0Documentation
Full Changelog: https://github.com/l2hyunwoo/nitro-webview/commits/v0.1.0