# Root Native Web: full documentation
> Every page of the docs site, in sidebar order. scripts/build-llms.mjs generates this file
> from docs/docs. Don't edit it by hand.
Docs: https://rootnative.github.io/web/
Source: https://github.com/rootnative/web
---
# Root Native Web
`@rootnative/web` is a standalone web runtime for React Native apps. You write `react-native`. It runs in the browser as a real web app.
> **WARNING: Early alpha**
>
> The API can still change between releases. Each page lists what ships today and what doesn't.
## Why
[react-native-web](https://github.com/necolas/react-native-web) tracks React Native and stops there. This project starts from the browser and asks a different question: what does a React Native app need to be a good web app?
- **Parity first.** Every `react-native` export that ships behaves as it does on iOS and Android.
- **Web second, behind the same API.** Semantic HTML, SEO, server rendering, DOM events, logical CSS properties, and the browser features that native doesn't have.
- **Modern only.** TypeScript, ESM, React 19. No Flow, no CommonJS, no `findDOMNode`, no `forwardRef`.
## How it works
Your app imports `react-native`. The [Vite plugin](https://rootnative.github.io/web/vite-plugin) resolves that name to `@rootnative/web`. In an Expo app, [`@rootnative/web-expo`](https://rootnative.github.io/web/expo) does it in place of react-native-web. Your app code uses three entry points:
| Layer | Import | What's in it |
| ------ | ------------------------ | --------------------------------------------------------------- |
| Parity | `@rootnative/web` | The React Native components and APIs |
| Web | `@rootnative/web/dom` | Browser features that native doesn't have, for example `
` |
| Server | `@rootnative/web/server` | Server rendering helpers |
Import `@rootnative/web/dom` and `@rootnative/web/server` only in code that runs on the web. The rest of your app stays the same code that runs on iOS and Android. A fourth entry, `@rootnative/web/vite`, is the Vite plugin, for `vite.config.ts` only.
## Next steps
- [Installation](https://rootnative.github.io/web/installation): set up a Vite app in four steps.
- [Expo](https://rootnative.github.io/web/expo): run an Expo app, also with Expo Router.
- [Status](https://rootnative.github.io/web/status): what ships today, what's planned, and how it's tested.
---
# Installation
You need React 19 and React DOM 19. This page uses Vite 8 and the package's Vite plugin. For another bundler, see [Without the plugin](https://rootnative.github.io/web/vite-plugin#without-the-plugin). For an Expo app, see [Expo](https://rootnative.github.io/web/expo).
## Install the package
```bash
npm install @rootnative/web
```
React and React DOM are peer dependencies. A Vite React app has them already.
## Add the Vite plugin
Your app imports `react-native`. The plugin resolves that name to `@rootnative/web`:
```ts title="vite.config.ts"
import { rootnative } from '@rootnative/web/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [react(), rootnative()],
})
```
It also resolves `.web.tsx` files first, defines `__DEV__`, and puts `'web'` in place of `Platform.OS`. See [Vite plugin](https://rootnative.github.io/web/vite-plugin).
## Add the types
TypeScript needs the same mapping. Add a declaration file to a folder that your `tsconfig.json` includes, for example `src/`:
```ts title="src/react-native.d.ts"
declare module 'react-native' {
export * from '@rootnative/web'
}
```
Keep this file free of top-level `import` and `export` lines. With one, the declaration stops working, and TypeScript reports `Cannot find module 'react-native'`.
The file also gives you the type of `__DEV__`.
If your app has `.web.tsx` files, tell TypeScript to look for them first:
```json title="tsconfig.json"
{
"compilerOptions": {
"moduleSuffixes": [".web", ""]
}
}
```
Keep the empty string. Without it, TypeScript finds only the `.web` files.
## Mount your app
A React Native app expects a root view that fills the screen. Give the page a full-height root element that lays out its child as flex:
```html title="index.html"
```
Then render your app into it with React DOM:
```tsx title="src/main.tsx"
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from './App'
createRoot(document.getElementById('root')!).render(
,
)
```
Now `flex: 1` on your root view fills the window, as it does on iOS and Android:
```tsx title="src/App.tsx"
import { StyleSheet, Text, View } from 'react-native'
export function App() {
return (
Hello from React Native
)
}
const styles = StyleSheet.create({
screen: { flex: 1, alignItems: 'center', justifyContent: 'center' },
title: { fontSize: 24 },
})
```
## Browser support
The package targets Chrome 95, Edge 95, Firefox 93, Safari 15.1, and iOS Safari 15.1. Where an older browser lacks a feature, the package uses a fallback.
See [Status](https://rootnative.github.io/web/status) for what ships today and how it's tested.
---
# Vite plugin
`rootnative()` from `@rootnative/web/vite` sets up Vite 8 for a React Native app. It has one option, [`worklets`](#worklets), for an app that uses Reanimated.
```ts title="vite.config.ts"
import { rootnative } from '@rootnative/web/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [react(), rootnative()],
})
```
## What it does
| Part | What it does |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `react-native` alias | Resolves the import name `react-native` to `@rootnative/web`. Only the exact name: a deep import such as `react-native/Libraries/Image` doesn't resolve. |
| Assets registry alias | Resolves `@react-native/assets-registry/registry` to `@rootnative/web/assets-registry`. Libraries such as `react-native-svg` import that module on the web. |
| Reanimated aliases | Resolves two `react-native-web` internal files, which Reanimated 4 reads its web style helpers from, to `@rootnative/web/style`. See [Compat exports](https://rootnative.github.io/web/compat). |
| `.web` files | Resolves `Button.web.tsx` before `Button.tsx` for an import of `./Button`, as Metro does for the web. Each extension gets a `.web` variant in front. Pre-bundled dependencies get the same list, so a library loads its `.web.js` files. |
| `__DEV__` | Defines the React Native global: `true` on the dev server, `false` in a production build. It follows `NODE_ENV`, as React's development mode does. Pre-bundled dependencies get it too. |
| `global` | Defines React Native's name for the global object as `globalThis`. Reanimated and Worklets read it. Pre-bundled dependencies get it too. |
| `Platform.OS` | Puts `'web'` in place of each `Platform.OS` read, so the minifier drops the code of the other platforms. |
Your own config wins. A `react-native` alias, or a `__DEV__` or `global` define in your config, keeps its value. A `resolve.extensions` list of your own gets the `.web` variants in front.
TypeScript doesn't read the Vite config. For `.web` files, add `moduleSuffixes` to `tsconfig.json`, as [Installation](https://rootnative.github.io/web/installation#add-the-types) shows.
## `worklets`
Reanimated needs the Babel plugin of `react-native-worklets`. Without it, the first Reanimated hook throws. A library built on Reanimated, such as `@rootnative/inertia`, needs it too. Metro runs that plugin through the Babel preset of the app. Vite doesn't run Babel, so set the option:
```ts title="vite.config.ts"
export default defineConfig({
plugins: [react(), rootnative({ worklets: true })],
})
```
Your app must have `react-native-worklets`, which Reanimated needs anyway, and `@babel/core`:
```bash npm2yarn
npm install --save-dev @babel/core
```
A package manager that installs peer dependencies, such as pnpm or npm, has `@babel/core` already, because it's a peer of `react-native-worklets`.
| What | Behavior |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Which files | Your code and the libraries. The plugin runs Babel only on a file that has a `'worklet'` directive, imports Reanimated or Worklets, or calls a Reanimated hook. Every other file skips Babel. |
| Pre-bundled packages | The dependency optimizer gets the same step, so a library with worklets works on the dev server. |
| Your Babel config | Not read. The step runs only the Worklets plugin. Don't add `react-native-worklets/plugin` to a Babel config of your own for the same files. |
| A missing package | The first file with a worklet stops the build with an error that names the package. |
| Default | `false`. An app with no Reanimated doesn't need Babel. |
## `Platform.OS`
The plugin changes a read of `Platform.OS` when `Platform` comes from `react-native` or `@rootnative/web`. Named, renamed, and namespace imports all count:
```tsx
import { Platform } from 'react-native'
const label = Platform.OS === 'ios' ? 'iPhone' : 'Web'
// The build sees 'web' === 'ios', so only 'Web' stays in the bundle.
```
At run time `Platform.OS` is `'web'` anyway, so only the bundle size changes. Some reads keep their code, for example when a local variable in the same file has the name `Platform`. On the dev server, pre-bundled dependencies keep their reads too. `Platform.select` keeps its code.
## Server rendering
With Vite's server rendering, the plugin applies to your app code on the server too.
Vite leaves most dependencies to Node, and Node doesn't get the `__DEV__` define. A dependency that reads `__DEV__` then throws a `ReferenceError` on the server. Add that dependency to `ssr.noExternal`, so that Vite transforms it:
```ts title="vite.config.ts"
export default defineConfig({
plugins: [react(), rootnative()],
ssr: { noExternal: ['some-library'] },
})
```
## Without the plugin
With another bundler, or without the plugin, set up the alias, the `.web` extensions, `__DEV__`, and `global` yourself. In Vite:
```ts title="vite.config.ts"
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'
const defaults = ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json']
const extensions = [...defaults.map((extension) => `.web${extension}`), ...defaults]
const define = {
__DEV__: JSON.stringify(process.env.NODE_ENV !== 'production'),
global: 'globalThis',
}
export default defineConfig({
plugins: [react()],
resolve: {
alias: [{ find: /^react-native$/, replacement: '@rootnative/web' }],
extensions,
},
define,
// The dependency optimizer has its own `define` and extension list, so pre-bundled
// libraries need them too.
optimizeDeps: { rolldownOptions: { transform: { define }, resolve: { extensions } } },
})
```
`Platform.OS` then stays a read at run time. It still returns `'web'`.
A library that needs a [compat entry](https://rootnative.github.io/web/compat) also needs its alias. The plugin adds these three:
| Import name | Alias to |
| ------------------------------------------------------------------------------ | --------------------------------- |
| `@react-native/assets-registry/registry` | `@rootnative/web/assets-registry` |
| `react-native-web/dist/cjs/exports/StyleSheet/compiler/createReactDOMStyle.js` | `@rootnative/web/style` |
| `react-native-web/dist/cjs/exports/StyleSheet/preprocess.js` | `@rootnative/web/style` |
---
# Expo
`@rootnative/web-expo` runs an Expo app on `@rootnative/web` in place of react-native-web. You keep your Expo setup: the dev server, `expo export`, and the Babel preset.
## Install
Install the package under the name `react-native-web`, with an npm alias:
```bash npm2yarn
npm install react-native-web@npm:@rootnative/web-expo
```
An Expo app with web support lists `react-native-web` already, and the alias takes its place. Restart the dev server with `--clear` after the change:
```bash
npx expo start --clear
```
Your code doesn't change, and TypeScript keeps the types of the `react-native` package.
The package depends on the same version of `@rootnative/web`, and works only with that version. If your app imports `@rootnative/web` itself, for example [`Head`](https://rootnative.github.io/web/seo) from `@rootnative/web/dom`, install the version that the package names.
## How it works
On the web, Expo's Babel preset rewrites `import { View } from 'react-native'` to an import of `react-native-web/dist/exports/View`. The package has a file at each of these paths, and each file loads only its own module of `@rootnative/web`. So the bundle has only the components that your app imports.
Expo also calls `AppRegistry` from `react-native-web` to start the app, and asks it for the reset styles of the page. The package gives both: your app renders with React DOM, and `body` gets no margin, as with react-native-web.
Expo's libraries import `UIManager`, `NativeModules`, `LogBox`, `DeviceEventEmitter`, `NativeEventEmitter`, and `AssetRegistry` on the web too. The package gives them as react-native-web does: `NativeModules` has no native module, `LogBox` does nothing, `UIManager` measures an element with the host methods of `@rootnative/web`, only JavaScript emits events on the two emitters, and `AssetRegistry` is the asset registry of `@rootnative/web`.
## What works
| Part | Behavior |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Components and APIs | Each one that `@rootnative/web` has. See [Status](https://rootnative.github.io/web/status). |
| Expo Router | Tabs, a stack, links, the back button, and a URL that opens a screen directly. |
| The dev server | Works. |
| `expo export --platform web` | Works with `web.output: 'single'`, the default, and with `'static'`: Expo Router renders each route on the server, and the page hydrates. |
| Reanimated 4 | Animates the components. Expo's Babel preset runs the Worklets plugin, so the app needs no setup. |
| Image imports | `require('./logo.png')` loads the image. On the web, Expo gives the import a `uri`, a `width`, and a `height`, and [`Image`](https://rootnative.github.io/web/image) reads them. |
| `react-native-svg` | Renders. The package has the assets registry that it loads on the web. |
## Names that aren't there yet
A name of `react-native` that `@rootnative/web` doesn't have yet loads as a stub. The import works, so a library that imports the name and doesn't use it still loads. A use throws an error that names it, such as `LayoutAnimation is not in @rootnative/web yet`.
The largest ones today are `LayoutAnimation`, `SectionList`, `VirtualizedList`, `ImageBackground`, and `SafeAreaView`. The file `node_modules/react-native-web/expo-exports.json` lists all of them under `missing`.
---
# Status
`@rootnative/web` is in early alpha. The API can change between alpha releases. This page lists what exists, so nothing on this site reads as a promise.
The latest release is [`0.0.0-alpha.6`](https://www.npmjs.com/package/@rootnative/web) on npm. The [changelog](https://github.com/rootnative/web/blob/main/packages/web/CHANGELOG.md) lists the changes in each release.
## What ships today
| Group | Exports |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Components | [`View`](https://rootnative.github.io/web/view), [`Text`](https://rootnative.github.io/web/text), [`Image`](https://rootnative.github.io/web/image), [`Pressable`](https://rootnative.github.io/web/pressable), [`TouchableHighlight`](https://rootnative.github.io/web/touchablehighlight), [`TouchableNativeFeedback`](https://rootnative.github.io/web/touchablenativefeedback), [`TouchableOpacity`](https://rootnative.github.io/web/touchableopacity), [`TouchableWithoutFeedback`](https://rootnative.github.io/web/touchablewithoutfeedback), [`Button`](https://rootnative.github.io/web/button), [`ScrollView`](https://rootnative.github.io/web/scrollview), [`FlatList`](https://rootnative.github.io/web/flatlist), [`RefreshControl`](https://rootnative.github.io/web/refreshcontrol), [`TextInput`](https://rootnative.github.io/web/textinput), [`Switch`](https://rootnative.github.io/web/switch), [`ActivityIndicator`](https://rootnative.github.io/web/activityindicator), [`Modal`](https://rootnative.github.io/web/modal), [`KeyboardAvoidingView`](https://rootnative.github.io/web/keyboardavoidingview), [`StatusBar`](https://rootnative.github.io/web/statusbar) |
| APIs | [`StyleSheet`](https://rootnative.github.io/web/stylesheet), [`Platform`](https://rootnative.github.io/web/platform), [`Dimensions`](https://rootnative.github.io/web/dimensions), [`useWindowDimensions`](https://rootnative.github.io/web/dimensions), [`Appearance`](https://rootnative.github.io/web/appearance), [`useColorScheme`](https://rootnative.github.io/web/appearance), [`AppState`](https://rootnative.github.io/web/appstate), [`Keyboard`](https://rootnative.github.io/web/keyboard), [`Linking`](https://rootnative.github.io/web/linking), [`Alert`](https://rootnative.github.io/web/alert), [`Share`](https://rootnative.github.io/web/share), [`Vibration`](https://rootnative.github.io/web/vibration), [`Clipboard`](https://rootnative.github.io/web/clipboard), [`AccessibilityInfo`](https://rootnative.github.io/web/accessibilityinfo), [`I18nManager`](https://rootnative.github.io/web/i18nmanager), [`BackHandler`](https://rootnative.github.io/web/backhandler), [`PixelRatio`](https://rootnative.github.io/web/pixelratio), [`processColor`](https://rootnative.github.io/web/processcolor), [`PanResponder`](https://rootnative.github.io/web/panresponder), [`Animated`](https://rootnative.github.io/web/animated), [`Easing`](https://rootnative.github.io/web/easing), [`usePressability`](https://rootnative.github.io/web/usepressability) |
| Compat | [`unstable_createElement`](https://rootnative.github.io/web/compat), [`findNodeHandle`](https://rootnative.github.io/web/compat), [`TurboModuleRegistry`](https://rootnative.github.io/web/compat), and the entries `@rootnative/web/assets-registry` and `@rootnative/web/style`. Libraries import them, your app doesn't. |
| Web layer | [`Head`](https://rootnative.github.io/web/seo), from `@rootnative/web/dom` |
| Server | `createStyleRegistry`, `StyleRegistryProvider`, `renderStyleTags`, `styleTagsHTML`, `StyleRegistry`, from `@rootnative/web/server`. See [Server rendering](https://rootnative.github.io/web/server-rendering). |
| Tooling | [`rootnative()`](https://rootnative.github.io/web/vite-plugin), the Vite plugin, from `@rootnative/web/vite`, and [`@rootnative/web-expo`](https://rootnative.github.io/web/expo), for an Expo app, also with Expo Router |
`FlatList` renders every item. It has no virtualizer yet, so keep long lists short for now.
## Planned, not written
**Don't import these yet.** They aren't in the package.
- **Lists and motion:** a virtualizer for `FlatList`, `SectionList`, `VirtualizedList`, `LayoutAnimation`, and the rest of [`Animated`](https://rootnative.github.io/web/animated#not-there-yet).
- **Tooling:** a Next.js plugin, and templates for a Vite app with and without server rendering.
## Out of scope
- The `react-native-web` internals. Only `@rootnative/web-expo` has its file layout, for Expo's bundler.
- Metro with no Expo. A Metro plugin isn't planned for 1.0.
- React 18, CommonJS, and Flow.
- Props that React Native doesn't have, except a small web-only set. Each page marks a web-only prop.
## How it's tested
Every component and API has tests. They run in real browsers through Vitest browser mode, not in a simulated DOM: Chromium, Firefox, and WebKit, the engine of Safari.
---
# Semantic HTML
The `role` prop picks the HTML element. You don't need a web-only component or a web-only prop.
```tsx
Title
One
About
```
```html
Title
One
About
```
Screen readers, search engines, and browser features such as reader mode get the same structure that native accessibility tools get.
## Roles that pick an element
| `role` | Element |
| ------------------ | ------------------------------------------------------------- |
| `article` | `` |
| `banner` | `` |
| `button` | `