Skip to content

Commit cbd0066

Browse files
dannyhwdannyhw
committed
config and addons docs
1 parent 598400a commit cbd0066

File tree

2 files changed

+365
-0
lines changed

2 files changed

+365
-0
lines changed

‎docs/docs/intro/addons.md

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Addons
2+
3+
Since react native storybook has a react native UI the web based addon panels need to be reimplemented for react native. Addons that don't include a ui should also be compatible with react native, for example msw and deep controls.
4+
5+
The addons made available by us are the following. There are more addons available via the community and you can also write your own addons.
6+
7+
| Addon | Package |
8+
| ----------- | ------------------------------------- |
9+
| actions | @storybook/addon-ondevice-actions |
10+
| backgrounds | @storybook/addon-ondevice-backgrounds |
11+
| controls | @storybook/addon-ondevice-controls |
12+
| notes | @storybook/addon-ondevice-notes |
13+
14+
## Configuration
15+
16+
To use these addons, add them to your `.storybook/main.ts`:
17+
18+
```ts
19+
import { StorybookConfig } from '@storybook/react-native';
20+
21+
const main: StorybookConfig = {
22+
addons: [
23+
'@storybook/addon-ondevice-controls',
24+
'@storybook/addon-ondevice-backgrounds',
25+
'@storybook/addon-ondevice-actions',
26+
'@storybook/addon-ondevice-notes',
27+
],
28+
};
29+
30+
export default main;
31+
```
32+
33+
## Actions
34+
35+
The Actions addon lets you log events and actions inside your stories. It's useful for verifying component interactions and event handling.
36+
37+
```sh
38+
npm install --save-dev @storybook/addon-ondevice-actions
39+
```
40+
41+
Use the `action` argType to log events:
42+
43+
```ts
44+
export default {
45+
component: Button,
46+
argTypes: {
47+
onPress: { action: 'pressed' },
48+
},
49+
} satisfies Meta<typeof Button>;
50+
```
51+
52+
## Backgrounds
53+
54+
The Backgrounds addon allows you to change background colors of your stories directly on the device. Perfect for testing components against different backgrounds.
55+
56+
```sh
57+
npm install --save-dev @storybook/addon-ondevice-backgrounds
58+
```
59+
60+
First, add the required decorator in `.storybook/preview.tsx`:
61+
62+
```ts
63+
import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
64+
65+
const preview: Preview = {
66+
decorators: [withBackgrounds], // This decorator is required
67+
parameters: {
68+
backgrounds: {
69+
default: 'light',
70+
values: [
71+
{ name: 'light', value: 'white' },
72+
{ name: 'dark', value: '#333' },
73+
],
74+
},
75+
},
76+
};
77+
78+
export default preview;
79+
```
80+
81+
You can then override these background options in individual stories:
82+
83+
```ts
84+
export default {
85+
component: MyComponent,
86+
parameters: {
87+
backgrounds: {
88+
default: 'warm',
89+
values: [
90+
{ name: 'warm', value: 'hotpink' },
91+
{ name: 'cool', value: 'deepskyblue' },
92+
],
93+
},
94+
},
95+
} satisfies Meta<typeof MyComponent>;
96+
```
97+
98+
Component-level background settings will override the global settings from preview.tsx, but the decorator is still required.
99+
100+
## Controls
101+
102+
Controls provides a graphical UI to dynamically edit component props without code. It requires additional dependencies for form inputs:
103+
104+
```sh
105+
npm install --save-dev @storybook/addon-ondevice-controls @react-native-community/datetimepicker @react-native-community/slider
106+
```
107+
108+
Controls can be defined in multiple ways:
109+
110+
1. Inferred from `args` values:
111+
112+
```ts
113+
export default {
114+
component: MyComponent,
115+
args: {
116+
text: 'Hello', // infers text control
117+
enabled: true, // infers boolean control
118+
},
119+
} satisfies Meta<typeof MyComponent>;
120+
```
121+
122+
2. Inferred using TypeScript props with `babel-plugin-react-docgen-typescript`:
123+
124+
```js
125+
// babel.config.js
126+
module.exports = {
127+
plugins: [['babel-plugin-react-docgen-typescript', { exclude: 'node_modules' }]],
128+
};
129+
```
130+
131+
This will automatically create controls based on your component's types.
132+
133+
3. Define controls using argTypes:
134+
135+
```ts
136+
export default {
137+
component: MyComponent,
138+
argTypes: {
139+
text: { control: 'text' },
140+
enabled: { control: 'boolean' },
141+
color: { control: 'color' },
142+
size: { control: { type: 'range', min: 0, max: 100 } },
143+
type: { control: { type: 'radio', options: ['small', 'medium', 'large'] } },
144+
},
145+
} satisfies Meta<typeof MyComponent>;
146+
```
147+
148+
## Notes
149+
150+
The Notes addon enables you to write additional documentation (text or markdown) for your stories.
151+
152+
```sh
153+
npm install --save-dev @storybook/addon-ondevice-notes
154+
```
155+
156+
Add notes using the parameters field:
157+
158+
```ts
159+
export default {
160+
component: MyComponent,
161+
parameters: {
162+
notes: `
163+
# Component Documentation
164+
This is a markdown description of the component.
165+
166+
## Usage
167+
\`\`\`tsx
168+
<MyComponent prop="value" />
169+
\`\`\`
170+
`,
171+
},
172+
} satisfies Meta<typeof MyComponent>;
173+
```

‎docs/docs/intro/configuration.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Configuration
6+
7+
## Table of Contents
8+
9+
- [Configuration](#configuration)
10+
- [Table of Contents](#table-of-contents)
11+
- [Configuration Files](#configuration-files)
12+
- [main.ts](#maints)
13+
- [Options](#options)
14+
- [preview.tsx](#previewtsx)
15+
- [Notable Parameters](#notable-parameters)
16+
- [index.tsx](#indextsx)
17+
- [Available Options](#available-options)
18+
19+
## Configuration Files
20+
21+
### main.ts
22+
23+
The `main.ts` file is your primary configuration entry point, located in the `.storybook` directory.
24+
25+
```typescript
26+
import { StorybookConfig } from '@storybook/react-native';
27+
28+
const main: StorybookConfig = {
29+
stories: [
30+
// Simple glob pattern
31+
'../components/**/*.stories.?(ts|tsx|js|jsx)',
32+
33+
// Directory configuration with title prefix
34+
{
35+
directory: '../packages/ui',
36+
titlePrefix: 'UI',
37+
files: '**/*.stories.?(ts|tsx|js|jsx)',
38+
},
39+
],
40+
41+
addons: [
42+
'@storybook/addon-ondevice-controls',
43+
'@storybook/addon-ondevice-backgrounds',
44+
'@storybook/addon-ondevice-actions',
45+
'@storybook/addon-ondevice-notes',
46+
],
47+
};
48+
49+
export default main;
50+
```
51+
52+
#### Options
53+
54+
- `stories`: Array of story patterns or configuration objects
55+
- `directory`: Base directory for stories
56+
- `titlePrefix`: Optional prefix for story titles
57+
- `files`: Glob pattern for story files
58+
- `addons`: Array of addon packages to include
59+
- `reactNative.playFn`: Enable/disable story play functions
60+
61+
### preview.tsx
62+
63+
The `preview.tsx` file configures the story rendering environment and global parameters.
64+
65+
```typescript
66+
import { Preview } from '@storybook/react';
67+
import { View } from 'react-native';
68+
import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
69+
70+
const preview: Preview = {
71+
decorators: [
72+
// Global wrapper for all stories
73+
(Story) => (
74+
<View style={{ padding: 8 }}>
75+
<Story />
76+
</View>
77+
),
78+
79+
// backgrounds addon decorator
80+
withBackgrounds,
81+
],
82+
83+
parameters: {
84+
// story sorting configuration, should only be configured in preview file.
85+
options: {
86+
storySort: {
87+
method: 'alphabetical',
88+
includeNames: true,
89+
order: ['Components', 'Examples'],
90+
},
91+
},
92+
93+
// UI Configuration
94+
hideFullScreenButton: false,
95+
noSafeArea: false,
96+
97+
// Background Configuration
98+
backgrounds: {
99+
default: 'light',
100+
values: [
101+
{ name: 'light', value: 'white' },
102+
{ name: 'dark', value: '#333' },
103+
],
104+
},
105+
106+
// your own parameters
107+
my_param: 'anything',
108+
},
109+
};
110+
111+
export default preview;
112+
```
113+
114+
#### Notable Parameters
115+
116+
Other than story sort the other parameters can be overwritten per story.
117+
118+
- `parameters.options.storySort`: Story sorting configuration
119+
- `parameters.hideFullScreenButton`: Toggle fullscreen button visibility
120+
- `parameters.noSafeArea`: Disable safe area insets
121+
- `parameters.backgrounds`: Background addon configuration
122+
123+
### index.tsx
124+
125+
The entry point file configures the Storybook UI and runtime behavior.
126+
127+
```typescript
128+
import { view } from './storybook.requires';
129+
import AsyncStorage from '@react-native-async-storage/async-storage';
130+
131+
const StorybookUIRoot = view.getStorybookUI({
132+
// UI Configuration
133+
onDeviceUI: true,
134+
shouldPersistSelection: true,
135+
136+
// Theme Customization
137+
theme: {
138+
// theme documentation coming soon, for now use types to understand the available options
139+
},
140+
141+
// Story Selection
142+
initialSelection: {
143+
kind: 'Components/Button',
144+
name: 'Primary',
145+
},
146+
147+
// Storage Configuration
148+
storage: {
149+
getItem: AsyncStorage.getItem,
150+
setItem: AsyncStorage.setItem,
151+
},
152+
153+
// Websocket Options
154+
enableWebsockets: false,
155+
host: 'localhost',
156+
port: 7007,
157+
secured: false,
158+
query: '',
159+
});
160+
161+
export default StorybookUIRoot;
162+
```
163+
164+
#### Available Options
165+
166+
- **UI Options**
167+
168+
- `onDeviceUI`: Enable/disable on-device UI (default: true)
169+
- `shouldPersistSelection`: Persist last viewed story (default: true)
170+
171+
- **Theme Options**
172+
173+
- `theme`: Customize UI theme and branding
174+
175+
- **Story Selection**
176+
177+
- `initialSelection`: Set initial story to display
178+
- String format: `'kind--story'`
179+
- Object format: `{ kind: string, name: string }`
180+
181+
- **Storage Options**
182+
183+
- `storage`: Implementation for story persistence
184+
- `getItem`: Function to retrieve stored values
185+
- `setItem`: Function to store values
186+
187+
- **Websocket Options**
188+
- `enableWebsockets`: Enable remote control (default: false)
189+
- `host`: Websocket host (default: 'localhost')
190+
- `port`: Websocket port (default: 7007)
191+
- `secured`: Use WSS protocol (default: false)
192+
- `query`: Additional query parameters

0 commit comments

Comments
 (0)