From d0ca7585ab2939a40542183d512a42c1648451c1 Mon Sep 17 00:00:00 2001 From: Nicolas Gallagher Date: Fri, 25 May 2018 14:48:10 -0700 Subject: [PATCH] Update docs Close #960 --- README.md | 138 ++++++++++++++++++--- packages/website/guides/advanced.md | 2 +- packages/website/guides/getting-started.md | 49 +++++--- 3 files changed, 152 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index b7b5f6e0..0a95a9ed 100644 --- a/README.md +++ b/README.md @@ -2,41 +2,48 @@ [![npm version][package-badge]][package-url] [![Build Status][ci-badge]][ci-url] [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://reactjs.org/docs/how-to-contribute.html#your-first-pull-request) -"React Native for Web" brings the platform-agnostic Components and APIs of -[React Native][react-native-url] to the Web. +**Compatibility: React Native 0.55**. -* **High-quality user interfaces**: React Native for Web makes it easy to +"React Native for Web" makes it possible to run [React +Native][react-native-url] components and APIs on the web using React DOM. Check +out the live demo of the [React Native examples][examples-url] running on the +web. + +* **High-quality web interfaces**: makes it easy to create [fast](https://github.com/necolas/react-native-web/blob/master/packages/benchmarks/README.md), -adaptive web UIs in JavaScript. It provides native-like interactions, support +adaptive web UIs in JavaScript. It provides native-quality interactions, support for multiple input modes (touch, mouse, keyboard), optimized vendor-prefixed styles, built-in support for RTL layout, built-in accessibility, and integrates with React Dev Tools. -* **Write once, render anywhere**: React Native for Web interoperates with -existing React DOM components and is compatible with the majority of the -React Native API. You can develop new components for native and web without -rewriting existing code. React Native for Web can also render to HTML and -critical CSS on the server using Node.js. +* **Write once, render anywhere**: interoperates with existing React DOM +components and is compatible with the majority of the React Native API. You can +develop new components for native and web without rewriting existing code. +React Native for Web can also render to HTML and critical CSS on the server +using Node.js. -Who is using React Native for Web? [Twitter](https://mobile.twitter.com), -[Major League Soccer](https://matchcenter.mlssoccer.com), +Who is using React Native in production web apps? +[Twitter](https://mobile.twitter.com), [Major League +Soccer](https://matchcenter.mlssoccer.com), [Flipkart](https://www.flipkart.com/), Playstation, Uber, [The -Times](https://github.com/newsuk/times-components), [React Native's -documentation](http://facebook.github.io/react-native/). +Times](https://github.com/newsuk/times-components). Browser support: Chrome, Firefox, Edge, Safari 7+, IE 10+. ## Quick start -The easiest way to get started with React Native for Web is to use this +The easiest way to get started is to edit this [CodeSandbox](https://codesandbox.io/s/q4qymyp2l6) template (or [Glitch](https://glitch.com/edit/#!/react-native)). You don’t need to install anything to try it out. +For installation and configuration details please read the [getting +started](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/getting-started.md) +guide. + ## Documentation -You can find the React Native for Web API documentation [on the -website][website-url]. +You can find the API documentation [on the website][website-url]. Please refer to the [React Native documentation][react-native-url] for more design details, and for information about the [Gesture Responder @@ -50,13 +57,15 @@ and [animations](https://facebook.github.io/react-native/docs/animations.html). * [Accessibility](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/accessibility.md) * [Internationalization](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/internationalization.md) * [Direct manipulation](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/direct-manipulation.md) -* [Advanced use](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/advanced.md) +* [Experimental / unstable use](https://github.com/necolas/react-native-web/blob/master/packages/website/guides/advanced.md) ## Examples -There are several examples [on the website][website-url] and in the [website's -source code](https://github.com/necolas/react-native-web/blob/master/packages/website). -Here is an example to get you started: +There are examples [on the website][website-url] ([source +code](https://github.com/necolas/react-native-web/blob/master/packages/website). +And all the [React Native examples][examples-url] ([source +code](https://github.com/necolas/react-native-web/blob/master/packages/examples)) +are also available. Here is an example to get you started: ```js import React from 'react'; @@ -98,6 +107,94 @@ Examples of using React Native for Web with other web tools: * [Storybook](https://github.com/necolas/react-native-web/tree/master/packages/website/storybook/.storybook) * [Styleguidist](https://github.com/styleguidist/react-styleguidist/tree/master/examples/react-native) +Example recipes for web-specific UI patterns: + +* [Links](https://codesandbox.io/s/53r88k5opx) +* [Hover styles](https://codesandbox.io/s/o9q8vy70l5) +* [Root element styles](https://codesandbox.io/s/52x1871vjl) + +## Compatibility with React Native + +React Native v0.55 + +### Components + +| Name | Status | Notes | +| :----------------------- | :------------------ | :---- | +| ActivityIndicator | Available | | +| ART | Available | | +| Button | Available | | +| CheckBox | Available | | +| FlatList | Available | | +| Image | Available (partial) | Missing multiple sources and HTTP headers. | +| ImageBackground | Available | | +| KeyboardAvoidingView | Available (mock) | | +| ListView | Available | | +| Modal | Not started | | +| Picker | Available | | +| RefreshControl | Not started | | +| SafeAreaView | Available | | +| ScrollView | Available (partial) | Missing momentum scroll events. | +| SectionList | Available | | +| Slider | Not started | | +| StatusBar | Mock | | +| SwipeableFlatList | Available | | +| SwipeableListView | Available | | +| Switch | Available | | +| Text | Available (partial) | Missing `onLongPress` support. | +| TextInput | Available (partial) | Missing rich text features and auto-expanding behaviour. | +| Touchable | Available | Includes additional support for mouse and keyboard interactions. | +| TouchableHighlight | Available | | +| TouchableNativeFeedback | Not started | | +| TouchableOpacity | Available | | +| TouchableWithoutFeedback | Available | | +| View | Available | | +| VirtualizedList | Available | | +| WebView | Not started | | +| YellowBox | Mock | | + +### Modules + +| Name | Status | Notes | +| :----------------------- | :------------------ | :---- | +| AccessibilityInfo | Mock | No equivalent web APIs. | +| Alert | Not started | | +| Animated | Available | Missing `useNativeDriver` support. | +| AppRegistry | Available | Includes additional support for SSR with `getApplication`. | +| AppState | Available | | +| AsyncStorage | Available | | +| BackHandler | Mock | No equivalent web APIs. | +| CameraRoll | Not started | No equivalent web APIs. | +| Clipboard | Available | | +| ColorPropType | Available | | +| DeviceInfo | Available (partial) | | +| Dimensions | Available | | +| Easing | Available | | +| EdgeInsetsPropType | Available | | +| Geolocation | Available | | +| I18nManager | Available | Includes additional support for runtime switch to RTL. | +| ImageEditor | Not started | No equivalent web APIs. | +| ImageStore | Not started | No equivalent web APIs. | +| InteractionManager | Available (partial) | | +| Keyboard | Mock | | +| LayoutAnimation | Available (partial) | Missing transform to web animation. | +| Linking | Available | | +| NativeEventEmitter | Available | | +| NativeMethodsMixin | Available | | +| NativeModules | Available (partial) | Mocked. Missing ability to load native modules. | +| NetInfo | Available (partial) | Missing functionality to detect extensive connections. | +| PanResponder | Available | | +| PixelRatio | Available | | +| Platform | Available | | +| PointPropType | Available | | +| Settings | Not started | | +| Share | Available | Only available over HTTPS. Read about the [Web Share API](https://wicg.github.io/web-share/). | +| StyleSheet | Available | | +| TextPropTypes | Available | | +| UIManager | Available | | +| Vibration | Available | | +| ViewPropTypes | Available | | + ## Contributing The main purpose of this repository is to help evolve React web and native @@ -135,6 +232,7 @@ MIT license. [package-url]: https://yarnpkg.com/en/package/react-native-web [ci-badge]: https://travis-ci.org/necolas/react-native-web.svg?branch=master [ci-url]: https://travis-ci.org/necolas/react-native-web +[examples-url]: https://necolas.github.io/react-native-web/examples/ [website-url]: https://necolas.github.io/react-native-web/storybook/ [react-native-url]: https://facebook.github.io/react-native/ [contributing-url]: https://github.com/necolas/react-native-web/blob/master/.github/CONTRIBUTING.md diff --git a/packages/website/guides/advanced.md b/packages/website/guides/advanced.md index f7544750..621ed517 100644 --- a/packages/website/guides/advanced.md +++ b/packages/website/guides/advanced.md @@ -1,4 +1,4 @@ -# Advanced use +# Experimental / unstable uses ## Use with existing React DOM components diff --git a/packages/website/guides/getting-started.md b/packages/website/guides/getting-started.md index 85cc8f0b..b4345c25 100644 --- a/packages/website/guides/getting-started.md +++ b/packages/website/guides/getting-started.md @@ -13,7 +13,7 @@ the recommendations in the [React documentation](https://reactjs.org/). ## Install ``` -yarn install react react-dom react-native-web +yarn add react react-dom react-native-web ``` And if you need to use `ART`: @@ -38,7 +38,7 @@ includes experimental support for Web. create-react-native-app my-app --with-web-support ``` -## Configure module bundler +## Configuring a module bundler If you have a custom setup, you may choose to configure your module bundler to alias the package to `react-native`. @@ -46,14 +46,14 @@ alias the package to `react-native`. For example, modify your [webpack](https://github.com/webpack/webpack) configuration as follows: -``` +```js // webpack.config.js module.exports = { // ...the rest of your config resolve: { alias: { - 'react-native': 'react-native-web' + 'react-native$': 'react-native-web' } } } @@ -61,6 +61,23 @@ module.exports = { Now you can create your components and applications with the React Native API. +## Configuring babel + +If you need to do the aliasing with Babel you can use +[babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) + +``` +{ + "plugins": [ + ["module-resolver", { + "alias": { + "^react-native$": "react-native-web" + } + }] + ] +} +``` + ## Client-side rendering Render apps using `AppRegistry`: @@ -140,18 +157,13 @@ ${html} ## Testing with Jest -[Jest](https://facebook.github.io/jest/) can be configured to alias -`react-native-web` and improve snapshots: +[Jest](https://facebook.github.io/jest/) can be configured using the provided +preset. This will map `react-native` to `react-native-web` and provide +appropriate mocks: ``` { - "moduleNameMapper": { - "react-native": "/node_modules/react-native-web" - }, - "snapshotSerializers": [ - "enzyme-to-json/serializer", - "react-native-web/jest/serializer" - ] + "preset": "react-native-web" } ``` @@ -272,8 +284,12 @@ const imageLoaderConfiguration = { }; module.exports = { - // your web-specific entry file - entry: path.resolve(appDirectory, 'index.web.js'), + entry: [ + // load any web API polyfills + // path.resolve(appDirectory, 'polyfills-web.js'), + // your web-specific entry file + path.resolve(appDirectory, 'index.web.js') + ], // configures where the build ends up output: { @@ -291,8 +307,9 @@ module.exports = { }, resolve: { + // This will only alias the exact import "react-native" alias: { - 'react-native': 'react-native-web' + 'react-native$': 'react-native-web' }, // If you're working on a multi-platform React Native app, web-specific // module implementations should be written in files using the extension