1 | # Storybook for React Native
|
2 |
|
3 | With Storybook for React Native you can design and develop individual React Native components without running your app.
|
4 |
|
5 | ![Storybook Screenshot](docs/assets/readme/screenshot.png)
|
6 |
|
7 | For more information visit: [storybook.js.org](https://storybook.js.org)
|
8 |
|
9 | ## Getting Started
|
10 |
|
11 | The `storybook` CLI tool can be used to add Storybook to your React Native app. Install the `storybook` tool if necessary and run it from your project directory with these commands:
|
12 |
|
13 | ```shell
|
14 | cd my-rn-app
|
15 | npx -p @storybook/cli sb init
|
16 | ```
|
17 |
|
18 | During installation it will ask if you want to install storybook server.
|
19 | It allows you to control the storybook from your web browser.
|
20 |
|
21 | The next thing you need to do is make Storybook UI visible in your app.
|
22 |
|
23 | ### CRNA, React Native vanilla
|
24 |
|
25 | The easiest way to use Storybook is to simply replace your App with the Storybook UI, which is possible by replacing `App.js` with a single line of code:
|
26 |
|
27 | ```js
|
28 | export default from './storybook';
|
29 | ```
|
30 |
|
31 | This will get you up and running quickly, but then you lose your app!
|
32 | There are multiple options here. for example, you can export conditionally:
|
33 |
|
34 | ```js
|
35 | import StorybookUI from './storybook';
|
36 |
|
37 | import App from './app';
|
38 |
|
39 | module.exports = __DEV__ ? StorybookUI : App;
|
40 | ```
|
41 |
|
42 | ### React Native Navigation, other complex use cases
|
43 |
|
44 | `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.
|
45 |
|
46 | ## Start Storybook server (optional)
|
47 |
|
48 | If you want to control storybook from browser/VS Code/websockets you need install and start the server.
|
49 |
|
50 | ```sh
|
51 | npm run storybook
|
52 | ```
|
53 |
|
54 | Now, you can open `<http://localhost:7007>` to view your storybook menus in the browser.
|
55 |
|
56 | ## Start App
|
57 |
|
58 | To see your Storybook stories on the device, you should start your mobile app for the `<platform>` of your choice (typically `ios` or `android`). (Note that due to an implementation detail, your stories will only show up in the left pane of your browser window after your device has connected to this storybook server.)
|
59 |
|
60 | For CRNA apps:
|
61 |
|
62 | ```sh
|
63 | npm run <platform>
|
64 | ```
|
65 |
|
66 | For RN apps:
|
67 | ```sh
|
68 | react-native run-<platform>
|
69 | ```
|
70 |
|
71 | Once your app is started, changing the selected story in web browser will update the story displayed within your mobile app.
|
72 |
|
73 | If you are using Android and you get the following error after running the app: `'websocket: connection error', 'Failed to connect to localhost/127.0.0.1:7007'`, you have to forward the port 7007 on your device/emulator to port 7007 on your local machine with the following command:
|
74 | `adb reverse tcp:7007 tcp:7007`
|
75 |
|
76 | ## Start Command Parameters
|
77 |
|
78 | The following parameters can be passed to the start command:
|
79 |
|
80 | ```
|
81 | -h, --host <host>
|
82 | host to listen on
|
83 | -p, --port <port>
|
84 | port to listen on
|
85 | --https
|
86 | whether server is running on https
|
87 | -c, --config-dir [dir-name]
|
88 | storybook config directory
|
89 | -e, --environment [environment]
|
90 | DEVELOPMENT/PRODUCTION environment for webpack
|
91 | -i, --manual-id
|
92 | allow multiple users to work with same storybook
|
93 | --smoke-test
|
94 | Exit after successful start
|
95 | ```
|
96 |
|
97 | ## getStorybookUI Options
|
98 |
|
99 | You can pass these parameters to getStorybookUI call in your storybook entry point:
|
100 |
|
101 | ```
|
102 | {
|
103 | onDeviceUI: Boolean (true)
|
104 | -- display navigator and addons on the device
|
105 | disableWebsockets: Boolean (false)
|
106 | -- allows to display stories without running storybook server. Should be used with onDeviceUI
|
107 | secured: Boolean (false)
|
108 | -- use wss/https instead of ws/http
|
109 | host: String (NativeModules.SourceCode.scriptURL)
|
110 | -- host to use
|
111 | port: Number (7007)
|
112 | -- port to use
|
113 | query: String ("")
|
114 | -- additional query string to pass to websockets
|
115 | isUIHidden: Boolean (false)
|
116 | -- should the ui be closed initially.
|
117 | tabOpen: Number (0)
|
118 | -- which tab should be open. -1 Navigator, 0 Preview, 1 Addons
|
119 | initialSelection: Object (null)
|
120 | -- initialize storybook with a specific story. In case a valid object is passed, it will take precedence over `shouldPersistSelection. ex: `{ kind: 'Knobs', story: 'with knobs' }`
|
121 | shouldPersistSelection: Boolean (true)
|
122 | -- initialize storybook with the last selected story.
|
123 | shouldDisableKeyboardAvoidingView: Boolean (false)
|
124 | -- Disable KeyboardAvoidingView wrapping Storybook's view
|
125 | keyboardAvoidingViewVerticalOffset: Number (0)
|
126 | -- With shouldDisableKeyboardAvoidingView=true, this will set the keyboardverticaloffset (https://facebook.github.io/react-native/docs/keyboardavoidingview#keyboardverticaloffset) value for KeyboardAvoidingView wrapping Storybook's view
|
127 | }
|
128 | ```
|
129 |
|
130 | ## Learn More
|
131 |
|
132 | Check the `docs` directory in this repo for more advanced setup guides and other info.
|