Skip to content

Commit

Permalink
Update RN guide for 5.1 (#6977)
Browse files Browse the repository at this point in the history 
Update RN guide for 5.1
  • Loading branch information
@shilman
shilman committed Jun 5, 2019
2 parents 76ab1b4 + 4750688 commit db75c0a
Showing 1 changed file with 65 additions and 63 deletions.
128 changes: 65 additions & 63 deletions docs/src/pages/guides/guide-react-native/index.md
View file
Expand Up @@ -3,7 +3,7 @@ id: 'guide-react-native'
title: 'Storybook for React Native'
---

This guide will help you to manually setup React Native Storybook and explain about addons and Storybook server.
This guide will help you to manually setup React Native Storybook and explain about addons and Storybook server.

## Automatic setup

Expand All @@ -27,13 +27,14 @@ npm i --save-dev @storybook/react-native
**2. Create the Storybook directory.**

Create a new directory called `storybook` in your project root.

**3. Create an entry file for Storybook.**

Create an `index.js` file as given below. Do not forget to replace `%APP_NAME%` with your app name if you are not
using expo.

``storybook/index.js``
`storybook/index.js`

```js
import { AppRegistry } from 'react-native';
import { getStorybookUI, configure } from '@storybook/react-native';
Expand All @@ -58,10 +59,10 @@ export default StorybookUIRoot;

**4. Create a file for on device addons**

Create a file called `rn-addons.js` that you can use to include on device addons (more about them in addons section).
You can see an example below.
Create a file called `rn-addons.js` that you can use to include on device addons (more about them in addons section). You can see an example below.

`storybook/rn-addons.js`

```
import '@storybook/addon-ondevice-knobs/register';
import '@storybook/addon-ondevice-notes/register';
Expand All @@ -70,20 +71,19 @@ import '@storybook/addon-ondevice-notes/register';

**5. Display StorybookUI in your app.**

Finally you need to expose StorybookUI somewhere in your app.
The easiest solution is to replace your app entry with:
Finally you need to expose StorybookUI somewhere in your app.
The easiest solution is to replace your app entry with:

```js
export default from './storybook';
```

If you cannot replace your entry point just make sure that the component exported from `./storybook` is displayed
somewhere in your app. `StorybookUI` is simply a RN `View` component that can be embedded anywhere in your
RN application, e.g. on a tab or within an admin screen.
If you cannot replace your entry point just make sure that the component exported from `./storybook` is displayed somewhere in your app. `StorybookUI` is simply a RN `View` component that can be embedded anywhere in your RN application, e.g. on a tab or within an admin screen.

---

## Writing stories

Now you can write some stories inside the `storybook/stories/index.js` file, like this:

```js
Expand All @@ -95,39 +95,31 @@ const style = {
flex: 1,
justifyContent: 'center',
alignItems: 'center',
backgroundColor: '#F5FCFF'
backgroundColor: '#F5FCFF',
};

const CenteredView = ({ children }) => (
<View style={style}>
{children}
</View>
);

storiesOf('CenteredView', module)
.add('default view', () => (
<CenteredView>
<Text>Hello Storybook</Text>
</CenteredView>
));
const CenteredView = ({ children }) => <View style={style}>{children}</View>;

storiesOf('CenteredView', module).add('default view', () => (
<CenteredView>
<Text>Hello Storybook</Text>
</CenteredView>
));
```

Refer to [Writing Stories](https://storybook.js.org/basics/writing-stories) for more information.



---

## Addons

Storybook supports addons. You can read more about them [here](https://storybook.js.org/addons/introduction)

There is one big difference in React Native is that it has two types of addons: Addons that work in the browser
and addons that work on the app itself (on device addons).
There is one big difference in React Native is that it has two types of addons: Addons that work in the browser and addons that work on the app itself (on device addons).

## Browser addons
Browser addons are default addons to storybook. You create a file called `addons.js` inside `storybook` directory and
the addons will be automatically loaded inside your browser.

Browser addons are default addons to storybook. You create a file called `addons.js` inside `storybook` directory and the addons will be automatically loaded inside your browser.

`storybook/addons.js`

Expand All @@ -137,21 +129,21 @@ import '@storybook/addon-knobs/register';
```

## On device addons
On device addons are addons that are displayed in your app in addons panel.
To use them you have to create a file called `rn-addons.js` in `storybook` directory.
Because React Native does not dynamically resolve imports, you will also have to manually import this file before
`getStorybookUI` call.

On device addons are addons that are displayed in your app in addons panel. To use them you have to create a file called `rn-addons.js` in `storybook` directory. Because React Native does not dynamically resolve imports, you will also have to manually import this file before the `getStorybookUI` call.

Example:

`storybook/rn-addons.js`

```js
import '@storybook/addon-ondevice-knobs/register';
import '@storybook/addon-ondevice-notes/register';
...
```

`storybook/index.js`

```js
import { getStorybookUI } from '@storybook/react-native';

Expand All @@ -166,46 +158,56 @@ export default StorybookUI;
This step is done automatically when you install Storybook for the first time.

## Compatibility

Web and onDevice addon compatibility can be found [here](https://github.com/storybookjs/storybook/blob/master/ADDONS_SUPPORT.md)

## Performance of on device addons
Because on device addons are inside the app, they are also rerendered on every change. Be aware that this can have
performance implications for your app.
---

Because on device addons are inside the app, they are also rerendered on every change. Be aware that this can have performance implications for your app.

---

## Storybook server
The default usage of React Native Storybook till version 4 involved starting Storybook server.
Starting from v4 we do not expect user to start the server since in most cases it is not really necessary.

In case you still want to run Storybook server simply add the following script to your `package.json`.
```json
{
"scripts": {
...
"storybook": "storybook start"
}
}
```

And then call `npm run storybook`.

Using Storybook server gives some additional functionality to Storybook for React Native.
Storybook RN server, `@storybook/react-native-server` is a seperate package that provides a standalone server that the Storybook ondevice client can connect to.

Running storybook server gives a few advantages over simply running on-device:

**Websockets connection.** By using websockets connection you can create your own tools that integrate with your storybook app and control it from outside of your app.

**IDE Plugins.** Running server allows you to control your storybook view from inside web page or your IDE. There is a plugin for [JetBrains IDEs](https://plugins.jetbrains.com/plugin/9910-storybook) and there is one for [VS Code](https://github.com/orta/vscode-react-native-storybooks).

**Web addons.** There are Storybook addons that work with React Native but do not have on device implementations.

**Websockets connection**
To run Storybook server, you need to install a few dependencies and add a run script to your `package.json`.

By using websockets connection you can create your own tools that integrate with your storybook app and control it from
outside of your app.
First:

**IDE Plugins**
```sh
npm i --save-dev @storybook/react-native-server babel-loader
```

Having server running allows you to control your storybook view from inside web page or your ide.
Then:

```json
{
"scripts": {
...
"storybook": "start-storybook -p 6006"
}
}
```

There is a plugin for [JetBrains IDEs](https://plugins.jetbrains.com/plugin/9910-storybook) and there is one
for [VS Code](https://github.com/orta/vscode-react-native-storybooks).
Finally:

```sh
npm run storybook
```

### Historical notes

**Web addons**
Some context may be useful if you've used older versions of Storybook for RN and find these instructions confusing.

There are Storybook addons that work with React Native but do not have on device implementations.
Prior to v4, `@storybook/react-native` included a built-in server and needed that server to function. In v4.x, the server became optional, but was still included in the package. Finally in v5, we've split out the server into its own package (as documented above), and this has a variety of maintenance and compatibility benefits.

For more information, see the RN migration instructions for [v4](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#removed-rn-packager) and [v5](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#react-native-server).

1 comment on commit db75c0a

@vercel
Copy link

@vercel vercel bot commented on db75c0a Jun 5, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully aliased the URL https://monorepo-gn0wc571x.now.sh to the following aliases.

Please sign in to comment.