# @rootnative/web
> A standalone web runtime for React Native apps. The app imports
> react-native, the Vite plugin resolves that name to @rootnative/web, and the
> app runs in the browser as a real web app: semantic HTML, atomic CSS, server
> rendering, and SEO tags. It doesn't use react-native-web.
Status: early alpha. The API can change between releases. Every component and
API has tests that run in real browsers: Chromium, Firefox, and WebKit, the
engine of Safari.
Docs: https://rootnative.github.io/web/
Full: https://rootnative.github.io/web/llms-full.txt
Source: https://github.com/rootnative/web
## Install
npm install @rootnative/web
Peers: react ^19.0.0, react-dom ^19.0.0. ESM only.
1. Add the Vite plugin (Vite 8) to vite.config.ts:
import { rootnative } from '@rootnative/web/vite'
plugins: [react(), rootnative()]
With Reanimated, or a library built on it: rootnative({ worklets: true }).
It runs the Babel plugin of react-native-worklets on the app code and the
libraries. The app needs react-native-worklets and @babel/core.
It resolves react-native to @rootnative/web (the exact name only), resolves
.web.* files first, defines __DEV__ (true on the dev server, false in a
production build, from NODE_ENV), and puts 'web' in place of Platform.OS.
It also defines global as globalThis, resolves
@react-native/assets-registry/registry to @rootnative/web/assets-registry,
resolves the two react-native-web style files that Reanimated 4 imports to
@rootnative/web/style, and gives pre-bundled dependencies the .web.*
extensions.
An alias or a __DEV__ define in your own config wins.
2. Add src/react-native.d.ts (in a folder that tsconfig.json includes):
declare module 'react-native' { export * from '@rootnative/web' }
The file must have no top-level import or export line. With one,
TypeScript reports "Cannot find module 'react-native'". Don't map the name
with tsconfig "paths": the package has no main or types field. The file
also gives the type of __DEV__. For .web.tsx files, add
"moduleSuffixes": [".web", ""] to tsconfig.json.
3. Give the page a full-height flex root:
html, body, #root { height: 100%; margin: 0 }
#root { display: flex; flex-direction: column }
Then createRoot(document.getElementById('root')!).render().
flex: 1 on the root View fills the window, as on iOS and Android.
Browsers: Chrome 95, Edge 95, Firefox 93, Safari 15.1, iOS Safari 15.1.
Without the plugin (another bundler): alias the exact name react-native to
@rootnative/web, put a .web variant of each extension first, and define
__DEV__ and global (as globalThis). In Vite, set the defines in define and in
optimizeDeps.rolldownOptions.transform.define, and the extensions in
resolve.extensions and optimizeDeps.rolldownOptions.resolve.extensions: the
dependency optimizer has its own. Add the compat aliases that a library
needs. Platform.OS then stays a read at run time.
Server rendering with Vite: the plugin applies to app code on the server. A
dependency that Vite leaves to Node gets no __DEV__ and throws a
ReferenceError. Add it to ssr.noExternal.
## Expo
An Expo app, also with Expo Router, runs on @rootnative/web through
@rootnative/web-expo, installed under the name react-native-web:
npm install react-native-web@npm:@rootnative/web-expo
Restart the dev server with --clear. The app code, the Babel preset, and the
react-native types stay. Expo's Babel preset rewrites each react-native import
to react-native-web/dist/exports/; the package has those files, and each
one loads only its own module of @rootnative/web, so the bundle has only the
components the app imports. It also gives Expo AppRegistry and the page reset
(body margin 0), and UIManager, NativeModules ({ UIManager }, no native
module), LogBox (no-ops), DeviceEventEmitter, NativeEventEmitter (only
JavaScript emits events), and AssetRegistry, as react-native-web does.
Works: the dev server, expo export --platform web with web.output 'single'
or 'static' (each route renders on the server, then hydrates), Expo Router
(tabs, a stack, links, back, a URL that opens a screen), Reanimated 4 (the
preset adds the Worklets plugin), image imports, react-native-svg.
web-expo depends on the exact same version of @rootnative/web: install that
version if the app imports @rootnative/web too.
A name that @rootnative/web lacks (LayoutAnimation, SectionList,
VirtualizedList, ImageBackground, SafeAreaView, and more) loads as a stub
that throws " is not in @rootnative/web yet" on use;
node_modules/react-native-web/expo-exports.json lists them under "missing".
## Entry points
- @rootnative/web: the React Native components and APIs. Import it as
react-native through the plugin.
- @rootnative/web/dom: web-only features. Head.
- @rootnative/web/server: createStyleRegistry, StyleRegistryProvider,
renderStyleTags, styleTagsHTML, StyleRegistry.
- @rootnative/web/vite: rootnative(), the Vite plugin. Only in vite.config.ts.
Libraries: react-native-svg, react-native-safe-area-context, and
@react-native-async-storage/async-storage need nothing more. Reanimated and
libraries on it need rootnative({ worklets: true }). An icon set of
@react-native-vector-icons needs its font from the app: import the .ttf of
the package with ?url, then document.fonts.add(new FontFace(name, url)).
Set skipLibCheck: true, because the type files of a native library import
the real react-native types.
Import /dom and /server only in code that runs on the web.
## What ships
Components: View, Text, Image, Pressable, TouchableHighlight,
TouchableNativeFeedback, TouchableOpacity, TouchableWithoutFeedback, Button,
ScrollView, FlatList, RefreshControl, TextInput, Switch, ActivityIndicator,
Modal, KeyboardAvoidingView, StatusBar.
APIs: StyleSheet, Platform, Dimensions, useWindowDimensions, Appearance,
useColorScheme, AppState, Keyboard, Linking, Alert, Share, Vibration, Clipboard,
AccessibilityInfo, I18nManager, BackHandler, PixelRatio, processColor,
PanResponder, Animated, Easing, usePressability.
Compat, for libraries only, do not call in app code: unstable_createElement,
findNodeHandle, TurboModuleRegistry.
NOT IMPLEMENTED, do not import:
- SectionList, VirtualizedList, LayoutAnimation.
- Animated: ValueXY, Color, decay, sequence, stagger, loop, delay, subtract,
divide, modulo, diffClamp, forkEvent, unforkEvent, attachNativeEvent,
Animated.Image, Animated.ScrollView, Animated.FlatList,
Animated.SectionList, useAnimatedValue, useAnimatedValueXY,
useAnimatedColor.
- A Next.js plugin, and templates for a Vite app with and without server
rendering.
Out of scope: Expo, Metro, React 18, CommonJS, Flow.
A component ref is the DOM element, typed HostInstance (ViewInstance,
TextInstance, ImageInstance, PressableInstance). It has measure(callback),
measureInWindow(callback), measureLayout(ancestor, onSuccess, onFail), and
setNativeProps({ style }). Each one calls its callback at once, with CSS
pixels from getBoundingClientRect(). The window is the visible area.
setNativeProps writes an inline style, and any other prop has no effect.
Type a ref as useRef(null), not useRef(null).
ScrollView, FlatList, and TextInput add the methods listed below.
## Semantic HTML
The role prop picks the element:
- article, figure, form, main: the element of the same name.
- banner: header. complementary: aside. contentinfo: footer.
navigation: nav. list: ul. listitem: li.
- button: