Skip to content

Commit cada67f

Browse files
necolasnecolas
committed
Reorganize documentation
Close #1092 Close #1095
1 parent b56a737 commit cada67f

13 files changed

+511
-459
lines changed

‎.github/ISSUE_TEMPLATE/bug.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,9 @@ Steps to reproduce:
3333
**Expected behavior**
3434
<!--
3535
REQUIRED: A clear and concise description of what you expected to happen.
36+
37+
Please check that the behaviour is not expected React Native behaviour by
38+
running your test case on iOS or Android using https://snack.expo.io.
3639
-->
3740

3841
**Environment (include versions). Did this work in previous versions?**

‎README.md

Lines changed: 112 additions & 106 deletions
Large diffs are not rendered by default.

‎packages/website/guides/accessibility.md renamed to ‎docs/guides/accessibility.md

File renamed without changes.

‎packages/website/guides/advanced.md renamed to ‎docs/guides/advanced.md

File renamed without changes.

‎docs/guides/client-side-rendering.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Client-side rendering
2+
3+
Render apps using `AppRegistry`:
4+
5+
```js
6+
// index.web.js
7+
8+
import App from './src/App';
9+
import React from 'react';
10+
import { AppRegistry } from 'react-native';
11+
12+
// register the app
13+
AppRegistry.registerComponent('App', () => App);
14+
15+
AppRegistry.runApplication('App', {
16+
initialProps: {},
17+
rootTag: document.getElementById('react-app')
18+
});
19+
```
20+
21+
Or render individual components:
22+
23+
```js
24+
import AppHeader from './src/AppHeader';
25+
import React from 'react';
26+
import { render } from 'react-native';
27+
28+
render(<AppHeader />, document.getElementById('react-app-header'))
29+
```
30+
31+
(Components will also be rendered within a tree produced by calling
32+
`ReactDOM.render` (i.e., an existing web app), but
33+
otherwise it is not recommended.)
34+
35+
You might need to adjust the styles of the HTML document's root elements for
36+
your app to fill the viewport.
37+
38+
```html
39+
<html style="height:100%">
40+
<body style="height:100%">
41+
<div id="react-root" style="display:flex;height:100%"></div>
42+
```

‎packages/website/guides/direct-manipulation.md renamed to ‎docs/guides/direct-manipulation.md

File renamed without changes.

‎docs/guides/getting-started.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Getting started
2+
3+
This guide will help you render components and applications with React Native
4+
for Web.
5+
6+
Your application may need to polyfill `Promise`, `Object.assign`, `Array.from`,
7+
and [`ResizeObserver`](https://github.com/que-etc/resize-observer-polyfill) as
8+
necessary for your desired browser support.
9+
10+
If you're not familiar with setting up a new React web project, please follow
11+
the recommendations in the [React documentation](https://reactjs.org/).
12+
13+
## Install
14+
15+
```
16+
yarn add react react-dom react-native-web
17+
```
18+
19+
And if you need to use `ART`:
20+
21+
```
22+
yarn add react-art
23+
```
24+
25+
## Starter kits
26+
27+
Web: [create-react-app](https://github.com/facebookincubator/create-react-app)
28+
includes built-in support for aliasing `react-native-web` to `react-native`.
29+
30+
```
31+
create-react-app my-app
32+
```
33+
34+
Multi-platform: [create-react-native-app](https://github.com/react-community/create-react-native-app)
35+
includes experimental support for Web.
36+
37+
```
38+
create-react-native-app my-app --with-web-support
39+
```
40+
41+
## Configuring a module bundler
42+
43+
If you have a custom setup, you may choose to configure your module bundler to
44+
alias the package to `react-native`.
45+
46+
For example, modify your [webpack](https://github.com/webpack/webpack)
47+
configuration as follows:
48+
49+
```js
50+
// webpack.config.js
51+
module.exports = {
52+
// ...the rest of your config
53+
54+
resolve: {
55+
alias: {
56+
'react-native$': 'react-native-web'
57+
}
58+
}
59+
}
60+
```
61+
62+
Now you can create your components and applications with the React Native API.
63+
64+
## Configuring Babel
65+
66+
If you need to do the aliasing with Babel you can use
67+
[babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver)
68+
69+
```
70+
{
71+
"plugins": [
72+
["module-resolver", {
73+
"alias": {
74+
"^react-native$": "react-native-web"
75+
}
76+
}]
77+
]
78+
}
79+
```
80+
81+
## Configuring Jest
82+
83+
[Jest](https://facebook.github.io/jest/) can be configured using the provided
84+
preset. This will map `react-native` to `react-native-web` and provide
85+
appropriate mocks:
86+
87+
```
88+
{
89+
"preset": "react-native-web"
90+
}
91+
```
92+
93+
Please refer to the Jest documentation for more information.
94+
95+
## Configuring Flow
96+
97+
[Flow](https://flow.org) can be configured to understand the aliased module:
98+
99+
```
100+
[options]
101+
module.name_mapper='^react-native$' -> 'react-native-web'
102+
```
103+
104+
You may also need to include a custom libdef
105+
([example](https://gist.github.com/paularmstrong/f60b40d16fc83e1e8e532d483336f9bb))
106+
in your config.
107+
108+
## Other notes
109+
110+
### Safari flexbox performance
111+
112+
Safari prior to version 10.1 can suffer from extremely [poor flexbox
113+
performance](https://bugs.webkit.org/show_bug.cgi?id=150445). The recommended
114+
way to work around this issue (as used on mobile.twitter.com) is to set
115+
`display:block` on Views in your element hierarchy that you know don't need
116+
flexbox layout.

‎packages/website/guides/internationalization.md renamed to ‎docs/guides/internationalization.md

File renamed without changes.

‎docs/guides/multi-platform-apps.md

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Multi-platform applications
2+
3+
## Web-specific code
4+
5+
Minor platform differences can use the `Platform` module.
6+
7+
```js
8+
import { Platform } from 'react-native';
9+
10+
const styles = StyleSheet.create({
11+
height: (Platform.OS === 'web') ? 200 : 100,
12+
});
13+
```
14+
15+
More significant platform differences should use platform-specific files (see
16+
the webpack configuration below for resolving `*.web.js` files):
17+
18+
For example, with the following files in your project:
19+
20+
```
21+
MyComponent.android.js
22+
MyComponent.ios.js
23+
MyComponent.web.js
24+
```
25+
26+
And the following import:
27+
28+
```js
29+
import MyComponent from './MyComponent';
30+
```
31+
32+
React Native will automatically import the correct variant for each specific
33+
target platform.
34+
35+
## Web packaging for existing React Native apps
36+
37+
What follows is merely an _example_ of one basic way to package a web app using
38+
[Webpack](https://webpack.js.org) and [Babel](https://babeljs.io/). (You can
39+
also the React Native bundler, [Metro](https://github.com/facebook/metro), to
40+
build web apps.)
41+
42+
Packaging web apps is subtly different to packaging React Native apps and is
43+
complicated by the need to tree-shake and code-split non-trivial apps.
44+
45+
Install webpack-related dependencies, for example:
46+
47+
```
48+
yarn add --dev babel-loader url-loader webpack webpack-cli webpack-dev-server
49+
```
50+
51+
React Native's Babel preset rewrites ES modules to CommonJS modules, preventing
52+
bundlers from automatically performing "tree-shaking" to remove unused modules
53+
from your web app build. To help with this, you can install the following Babel
54+
plugin:
55+
56+
```
57+
yarn install --dev babel-plugin-react-native-web
58+
```
59+
60+
Create a `web/webpack.config.js` file:
61+
62+
```js
63+
// web/webpack.config.js
64+
65+
const path = require('path');
66+
const webpack = require('webpack');
67+
68+
const appDirectory = path.resolve(__dirname, '../');
69+
70+
// This is needed for webpack to compile JavaScript.
71+
// Many OSS React Native packages are not compiled to ES5 before being
72+
// published. If you depend on uncompiled packages they may cause webpack build
73+
// errors. To fix this webpack can be configured to compile to the necessary
74+
// `node_module`.
75+
const babelLoaderConfiguration = {
76+
test: /\.js$/,
77+
// Add every directory that needs to be compiled by Babel during the build.
78+
include: [
79+
path.resolve(appDirectory, 'index.web.js'),
80+
path.resolve(appDirectory, 'src'),
81+
path.resolve(appDirectory, 'node_modules/react-native-uncompiled')
82+
],
83+
use: {
84+
loader: 'babel-loader',
85+
options: {
86+
cacheDirectory: true,
87+
// The 'react-native' preset is recommended to match React Native's packager
88+
presets: ['react-native'],
89+
// Re-write paths to import only the modules needed by the app
90+
plugins: ['react-native-web']
91+
}
92+
}
93+
};
94+
95+
// This is needed for webpack to import static images in JavaScript files.
96+
const imageLoaderConfiguration = {
97+
test: /\.(gif|jpe?g|png|svg)$/,
98+
use: {
99+
loader: 'url-loader',
100+
options: {
101+
name: '[name].[ext]'
102+
}
103+
}
104+
};
105+
106+
module.exports = {
107+
entry: [
108+
// load any web API polyfills
109+
// path.resolve(appDirectory, 'polyfills-web.js'),
110+
// your web-specific entry file
111+
path.resolve(appDirectory, 'index.web.js')
112+
],
113+
114+
// configures where the build ends up
115+
output: {
116+
filename: 'bundle.web.js',
117+
path: path.resolve(appDirectory, 'dist')
118+
},
119+
120+
// ...the rest of your config
121+
122+
module: {
123+
rules: [
124+
babelLoaderConfiguration,
125+
imageLoaderConfiguration
126+
]
127+
},
128+
129+
resolve: {
130+
// This will only alias the exact import "react-native"
131+
alias: {
132+
'react-native$': 'react-native-web'
133+
},
134+
// If you're working on a multi-platform React Native app, web-specific
135+
// module implementations should be written in files using the extension
136+
// `.web.js`.
137+
extensions: [ '.web.js', '.js' ]
138+
}
139+
}
140+
```
141+
142+
To run in development from the root of your application:
143+
144+
```
145+
./node_modules/.bin/webpack-dev-server -d --config ./web/webpack.config.js --inline --hot --colors
146+
```
147+
148+
To build for production:
149+
150+
```
151+
./node_modules/.bin/webpack -p --config ./web/webpack.config.js
152+
```
153+
154+
Please refer to the Webpack documentation for more information on configuration.

‎docs/guides/server-side-rendering.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Server-side rendering
2+
3+
Server-side rendering to HTML is supported using `AppRegistry`:
4+
5+
```js
6+
import App from './src/App';
7+
import ReactDOMServer from 'react-dom/server';
8+
import { AppRegistry } from 'react-native-web';
9+
10+
// register the app
11+
AppRegistry.registerComponent('App', () => App);
12+
13+
// prerender the app
14+
const { element, getStyleElement } = AppRegistry.getApplication('App', { initialProps });
15+
// first the element
16+
const html = ReactDOMServer.renderToString(element);
17+
// then the styles (optionally include a nonce if your CSP policy requires it)
18+
const css = ReactDOMServer.renderToStaticMarkup(getStyleElement({ nonce }));
19+
20+
// example HTML document string
21+
const document = `
22+
<!DOCTYPE html>
23+
<html style="height:100%">
24+
<meta charset="utf-8">
25+
<meta name="viewport" content="width=device-width, initial-scale=1">
26+
${css}
27+
<body style="height:100%; overflow-y:hidden">
28+
<div id="root" style="display:flex; height: 100%">
29+
${html}
30+
</div>
31+
<script nonce="${nonce}" src="${bundlePath}"></script>
32+
`
33+
```

‎packages/website/guides/style.md renamed to ‎docs/guides/style.md

File renamed without changes.

0 commit comments

Comments
 (0)