Skip to content
Back to search

react-native-storybook

MarketplaceWorks with Claude CodeGitHub

πŸ““ Storybook for React Native!

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/storybookjs/react-native with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/storybookjs/react-native'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/storybookjs--react-native/badge.svg)](/listings/storybookjs--react-native)

HTML

<a href="/listings/storybookjs--react-native"><img src="/api/listings/storybookjs--react-native/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

New project

There is some project boilerplate with `@storybook/react-native` and `@storybook/addon-react-native-web` both already configured with a simple example.

For Expo you can use this [template](https://github.com/dannyhw/expo-template-storybook) with the following command

# With NPM
npx create-expo-app --template expo-template-storybook AwesomeStorybook

For React Native CLI you can use this [template](https://github.com/dannyhw/react-native-template-storybook)

npx @react-native-community/cli init MyApp --template react-native-template-storybook

Existing project

Run init to setup your project with all the dependencies and configuration files:

npm create storybook@latest

Then wrap your bundler config with the `withStorybook` function. It auto-detects Metro vs Re.Pack and handles everything β€” entry-point swapping, story generation, and optional WebSocket setup.

// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const { withStorybook } = require('@storybook/react-native/withStorybook');

const config = getDefaultConfig(__dirname);

module.exports = withStorybook(config);

No changes to `App.tsx` are needed. Set `STORYBOOK_ENABLED=true` and run:

STORYBOOK_ENABLED=true expo start

The wrapper automatically swaps your app's entry point with Storybook's entry point. When the variable is not set, your app runs normally with zero Storybook code in the bundle.

If you want to add everything yourself check out the [manual setup guide](https://storybookjs.github.io/react-native/docs/intro/getting-started/manual-setup).

Reanimated setup

Make sure you have `react-native-reanimated` in your project and the plugin setup in your babel config.

// babel.config.js
plugins: ['react-native-reanimated/plugin'],

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "react-native-storybook",
  3. "owner": {
  4. "name": "Storybook Community"
  5. },
  6. "metadata": {
  7. "description": "Storybook for React Native plugins",
  8. "version": "1.1.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "react-native-storybook",
  13. "source": {
  14. "source": "github",
  15. "repo": "storybookjs/react-native"
  16. },
  17. "description": "Create and edit React Native Storybook stories using Component Story Format (CSF). Includes controls reference, addon configuration, and portable story patterns.",
  18. "version": "1.1.0"
  19. }
  20. ]
  21. }
README.md Β· README Β· 446 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Storybook for React Native
  2. A new docs site is being built for Storybook for React Native, you can find it at https://storybookjs.github.io/react-native/docs/intro/.
  3. > [!IMPORTANT]
  4. > This readme is for v10, for v9 docs see the [v9.1 docs](https://github.com/storybookjs/react-native/tree/v9.1.4).
  5. With Storybook for React Native you can design and develop individual React Native components without running your app.
  6. If you are migrating from 9 to 10 you can find the migration guide [here](https://github.com/storybookjs/react-native/blob/next/MIGRATION.md#from-version-9-to-10)
  7. For more information about storybook visit: [storybook.js.org](https://storybook.js.org)
  8. > [!NOTE]
  9. > Make sure you align your storybook dependencies to the same major version or you will see broken behaviour.
  10. ![picture of storybook](https://github.com/user-attachments/assets/cf98766d-8b90-44ab-b718-94ab16e63205)
  11. ## Table of contents
  12. - πŸš€ [Getting Started](#getting-started)
  13. - πŸ“’ [Writing stories](#writing-stories)
  14. - πŸ”Œ [Addons](#addons)
  15. - πŸ“± [Hide/Show Storybook](#hideshow-storybook)
  16. - βš™οΈ [withStorybook wrapper](#withstorybook-wrapper)
  17. - πŸ”§ [getStorybookUI](#getstorybookui-options)
  18. - 🏁 [Feature Flags](#feature-flags)
  19. - πŸ§ͺ [Using stories in unit tests](#using-stories-in-unit-tests)
  20. - 🀝 [Contributing](#contributing)
  21. - ✨ [Examples](#examples)- [Storybook for React Native](#storybook-for-react-native)
  22. - πŸ€– [Agent skills](#agent-skills)
  23. ## Getting Started
  24. ### New project
  25. There is some project boilerplate with `@storybook/react-native` and `@storybook/addon-react-native-web` both already configured with a simple example.
  26. For Expo you can use this [template](https://github.com/dannyhw/expo-template-storybook) with the following command
  27. ```sh
  28. # With NPM
  29. npx create-expo-app --template expo-template-storybook AwesomeStorybook
  30. ```
  31. For React Native CLI you can use this [template](https://github.com/dannyhw/react-native-template-storybook)
  32. ```sh
  33. npx @react-native-community/cli init MyApp --template react-native-template-storybook
  34. ```
  35. ### Existing project
  36. Run init to setup your project with all the dependencies and configuration files:
  37. ```sh
  38. npm create storybook@latest
  39. ```
  40. Then wrap your bundler config with the `withStorybook` function. It auto-detects Metro vs Re.Pack and handles everything β€” entry-point swapping, story generation, and optional WebSocket setup.
  41. ```js
  42. // metro.config.js
  43. const { getDefaultConfig } = require('expo/metro-config');
  44. const { withStorybook } = require('@storybook/react-native/withStorybook');
  45. const config = getDefaultConfig(__dirname);
  46. module.exports = withStorybook(config);
  47. ```
  48. No changes to `App.tsx` are needed. Set `STORYBOOK_ENABLED=true` and run:
  49. ```sh
  50. STORYBOOK_ENABLED=true expo start
  51. ```
  52. The wrapper automatically swaps your app's entry point with Storybook's entry point. When the variable is not set, your app runs normally with zero Storybook code in the bundle.
  53. If you want to add everything yourself check out the [manual setup guide](https://storybookjs.github.io/react-native/docs/intro/getting-started/manual-setup).
  54. #### Reanimated setup
  55. Make sure you have `react-native-reanimated` in your project and the plugin setup in your babel config.
  56. ```js
  57. // babel.config.js
  58. plugins: ['react-native-reanimated/plugin'],
  59. ```
  60. ## Re.Pack setup
  61. For projects using [Re.Pack](https://re-pack.dev/) (Rspack/Webpack) instead of Metro, see the full [Re.Pack Setup guide](https://storybookjs.github.io/react-native/docs/intro/getting-started/repack). You can also reference the [RepackStorybookStarter](https://github.com/dannyhw/RepackStorybookStarter) project.
  62. ## Expo router specific setup
  63. For Expo Router projects, you can either use entry-point swapping (recommended) or create a dedicated Storybook route.
  64. See the full [Expo Router Setup guide](https://storybookjs.github.io/react-native/docs/intro/getting-started/expo-router) for details.
  65. ## Writing stories
  66. In Storybook we use a syntax called CSF that looks like this:
  67. ```tsx
  68. import type { Meta, StoryObj } from '@storybook/react-native';
  69. import { MyButton } from './Button';
  70. const meta = {
  71. component: MyButton,
  72. } satisfies Meta<typeof MyButton>;
  73. export default meta;
  74. type Story = StoryObj<typeof meta>;
  75. export const Basic: Story = {
  76. args: {
  77. text: 'Hello World',
  78. color: 'purple',
  79. },
  80. };
  81. ```
  82. You should configure the path to your story files in the `main.ts` config file from the `.rnstorybook` folder.
  83. ```ts
  84. // .rnstorybook/main.ts
  85. import type { StorybookConfig } from '@storybook/react-native';
  86. const main: StorybookConfig = {
  87. stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  88. deviceAddons: ['@storybook/addon-ondevice-controls', '@storybook/addon-ondevice-actions'],
  89. };
  90. export default main;
  91. ```
  92. ### Decorators and Parameters
  93. For stories you can add decorators and parameters on the default export or on a specific story.
  94. ```tsx
  95. import type { Meta } from '@storybook/react';
  96. import { Button } from './Button';
  97. const meta = {
  98. title: 'Button',
  99. component: Button,
  100. decorators: [
  101. (Story) => (
  102. <View style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
  103. <Story />
  104. </View>
  105. ),
  106. ],
  107. parameters: {
  108. backgrounds: {
  109. values: [
  110. { name: 'red', value: '#f00' },
  111. { name: 'green', value: '#0f0' },
  112. { name: 'blue', value: '#00f' },
  113. ],
  114. },
  115. },
  116. } satisfies Meta<typeof Button>;
  117. export default meta;
  118. ```
  119. For global decorators and parameters, you can add them to `preview.tsx` inside your `.rnstorybook` folder.
  120. ```tsx
  121. // .rnstorybook/preview.tsx
  122. import type { Preview } from '@storybook/react-native';
  123. import { withBackgrounds } from '@storybook/addon-ondevice-backgrounds';
  124. const preview: Preview = {
  125. decorators: [
  126. withBackgrounds,
  127. (Story) => (
  128. <View style={{ flex: 1, color: 'blue' }}>
  129. <Story />
  130. </View>
  131. ),
  132. ],
  133. parameters: {
  134. backgrounds: {
  135. default: 'plain',
  136. values: [
  137. { name: 'plain', value: 'white' },
  138. { name: 'warm', value: 'hotpink' },
  139. { name: 'cool', value: 'deepskyblue' },
  140. ],
  141. },
  142. },
  143. };
  144. export default preview;
  145. ```
  146. ## Addons
  147. The cli will install some basic addons for you such as controls and actions.
  148. Ondevice addons are addons that can render with the device ui that you see on the phone.
  149. Currently, the addons available are:
  150. - [`@storybook/addon-ondevice-controls`](https://storybook.js.org/addons/@storybook/addon-ondevice-controls): adjust your components props in realtime
  151. - [`@storybook/addon-ondevice-actions`](https://storybook.js.org/addons/@storybook/addon-ondevice-actions): mock onPress calls with actions that will log information in the actions tab
  152. - [`@storybook/addon-ondevice-notes`](https://storybook.js.org/addons/@storybook/addon-ondevice-notes): Add some Markdown to your stories to help document their usage
  153. - [`@storybook/addon-ondevice-backgrounds`](https://storybook.js.org/addons/@storybook/addon-ondevice-backgrounds): change the background of storybook to compare the look of your component against different backgrounds
  154. Install each one you want to use and add them to the `deviceAddons` list in your `main.ts`:
  155. ```ts
  156. // .rnstorybook/main.ts
  157. import type { StorybookConfig } from '@storybook/react-native';
  158. const main: StorybookConfig = {
  159. // ... rest of config
  160. deviceAddons: [
  161. '@storybook/addon-ondevice-notes',
  162. '@storybook/addon-ondevice-controls',
  163. '@storybook/addon-ondevice-backgrounds',
  164. '@storybook/addon-ondevice-actions',
  165. ],
  166. };
  167. export default main;
  168. ```
  169. > [!NOTE]
  170. > `deviceAddons` ensures on-device addons are only loaded at runtime on the device, avoiding errors during server-side operations. `.rnstorybook` does not read `addons`.
  171. ### Using the addons in your story
  172. For details of each ondevice addon you can see the readme:
  173. - [actions](https://github.com/storybookjs/react-native/tree/next/packages/ondevice-actions#readme)
  174. - [backgrounds](https://github.com/storybookjs/react-native/tree/next/packages/ondevice-backgrounds#readme)
  175. - [controls](https://github.com/storybookjs/react-native/tree/next/packages/ondevice-controls#readme)
  176. - [notes](https://github.com/storybookjs/react-native/tree/next/packages/ondevice-notes#readme)
  177. ## Hide/Show storybook
  178. Starting with v10.4, entry-point swapping is the default setup. Your existing in-app integration setup continues to work and is fully supported, but entry-point swapping is the recommended approach for new projects.
  179. ### Entry-point swapping (recommended, v10.4+)
  180. When using the bundler-agnostic `withStorybook` wrapper, set `STORYBOOK_ENABLED=true` to run Storybook. The wrapper swaps your app's entry point with Storybook's entry point automatically. When the variable is not set, your app runs normally with zero Storybook code in the bundle.
  181. ```json
  182. {
  183. "scripts": {
  184. "storybook": "STORYBOOK_ENABLED=true expo start",
  185. "storybook:ios": "STORYBOOK_ENABLED=true expo start --ios"
  186. }
  187. }
  188. ```
  189. ### Expo Router
  190. Create a dedicated route for Storybook:
  191. ```tsx
  192. // app/storybook.tsx
  193. export { default } from '../.rnstorybook';
  194. ```
  195. Then navigate to `/storybook` in your app to view stories.
  196. ### In-app integration (fully supported)
  197. You can also import Storybook directly in your `App.tsx`. This approach continues to work and is fully supported:
  198. ```tsx
  199. import StorybookUI from './.rnstorybook';
  200. import { MyApp } from './MyApp';
  201. const isStorybook = process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === 'true';
  202. export default function App() {
  203. return isStorybook ? <StorybookUI /> : <MyApp />;
  204. }
  205. ```
  206. ## withStorybook wrapper
  207. `withStorybook` is a bundler-agnostic wrapper that configures your project for Storybook. It auto-detects whether you're using Metro or Re.Pack and handles entry-point swapping, story generation, and WebSocket setup.
  208. ```js
  209. // metro.config.js
  210. const { getDefaultConfig } = require('expo/metro-config');
  211. const { withStorybook } = require('@storybook/react-native/withStorybook');
  212. const defaultConfig = getDefaultConfig(__dirname);
  213. module.exports = withStorybook(defaultConfig);
  214. ```
  215. When `STORYBOOK_ENABLED=true` is set, the wrapper activates. When it's not set, the wrapper is a no-op and your app runs normally.
  216. ### Options
  217. Options can be passed as a second argument. Most settings can also be controlled via environment variables (see [Environment Variables](https://storybookjs.github.io/react-native/docs/intro/configuration/environment-variables)).
  218. #### configPath
  219. Type: `string`, default: `path.resolve(process.cwd(), './.rnstorybook')`
  220. The location of your Storybook configuration directory, which includes `main.ts` and other project-related files.
  221. #### useJs
  222. Type: `boolean`, default: `false`
  223. Generates the `.rnstorybook/storybook.requires` file in JavaScript instead of TypeScript.
  224. #### docTools
  225. Type: `boolean`, default: `true`
  226. Whether to include doc tools in the storybook.requires file. Doc tools provide additional documentation features and work with `babel-plugin-react-docgen-typescript`.
  227. #### liteMode
  228. Type: `boolean`, default: `false`
  229. Whether to use lite mode for Storybook. In lite mode, the default Storybook UI is mocked out so you don't need to install all its dependencies like react-native-reanimated. This is useful for reducing bundle size and dependencies. Use this when using @storybook/react-native-ui-lite instead of @storybook/react-native-ui. Note: `STORYBOOK_DISABLE_UI=true` is equivalent to `onDeviceUI: false`, not `liteMode: true`.
  230. #### experimental_mcp
  231. Type: `boolean`, default: `false`
  232. Enables an experimental MCP (Model Context Protocol) server for AI tooling to query Storybook documentation and component/story metadata.
  233. The MCP server is available at the `/mcp` endpoint on the Storybook channel server. Configure your MCP client via its settings UI, or use:
  234. ```sh
  235. npx mcp-add --type http --url "http://localhost:7007/mcp" --scope project
  236. ```
  237. ### websockets
  238. Type: `'auto' | { host?: string, port?: number, secured?: boolean, key?: string | Buffer, cert?: string | Buffer, ca?: string | Buffer | Array<string | Buffer>, passphrase?: string }`, default: `undefined`
  239. If specified, create a WebSocket server on startup. This allows you to sync up multiple devices to show the same story and [arg](https://storybook.js.org/docs/writing-stories/args) values connected to the story in the UI.
  240. Use `'auto'` to automatically detect your LAN IP and inject host/port into the generated `storybook.requires` file. WebSocket settings can also be overridden via `STORYBOOK_WS_HOST`, `STORYBOOK_WS_PORT`, and `STORYBOOK_WS_SECURED` environment variables.
  241. > **Note:** A Metro-specific `withStorybook` is also available at `@storybook/react-native/metro/withStorybook` for advanced Metro configuration. See the [Metro Configuration docs](https://storybookjs.github.io/react-native/docs/intro/configuration/metro-configuration) for details.
  242. ## getStorybookUI options
  243. You can pass these parameters to getStorybookUI call in your storybook entry point:
  244. ```ts
  245. {
  246. initialSelection?: string | Object;
  247. storage?: {
  248. getItem: (key: string) => Promise<string | null>;
  249. setItem: (key: string, value: string) => Promise<void>;
  250. };
  251. onDeviceUI?: boolean;
  252. shouldPersistSelection?: boolean;
  253. theme: Partial<Theme>;
  254. }
  255. ```
  256. > **Note:** WebSocket options (`enableWebsockets`, `host`, `port`, `secured`) are auto-injected when using the bundler-agnostic `withStorybook` wrapper. You only need to set them manually if you're using the Metro-specific wrapper or a custom setup.
  257. ## Feature Flags
  258. Feature flags let you opt into new functionality without breaking existing behavior. In the next major version, the behavior behind these flags will become the default and the flags will no longer be needed.
  259. Add them to the `features` object in `main.ts`:
  260. ```ts
  261. // .rnstorybook/main.ts
  262. import type { StorybookConfig } from '@storybook/react-native';
  263. const main: StorybookConfig = {
  264. stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
  265. deviceAddons: ['@storybook/addon-ondevice-controls'],
  266. features: {
  267. ondeviceBackgrounds: true,
  268. },
  269. };
  270. export default main;
  271. ```
  272. | Flag | Description |
  273. | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
  274. | `ondeviceBackgrounds` | New backgrounds API with globals-based configuration, full-screen support, and no extra package needed. Available from v10.3. |
  275. For full documentation including configuration examples, see the [Feature Flags guide](https://storybookjs.github.io/react-native/docs/intro/configuration/feature-flags).
  276. ## Using stories in unit tests
  277. Storybook provides testing utilities that allow you to reuse your stories in external test environments, such as Jest. This way you can write unit tests easier and reuse the setup which is already done in Storybook, but in your unit tests. You can find more information about it in the [portable stories section](./PORTABLE_STORIES.md).
  278. ## Contributing
  279. We welcome contributions to Storybook!
  280. - πŸ“₯ Pull requests and 🌟 Stars are always welcome.
  281. - Read our [contributing guide](CONTRIBUTING.md) to get started,
  282. or find us on [Discord](https://discord.gg/sMFvFsG) and look for the react-native channel.
  283. Looking for a first issue to tackle?
  284. - We tag issues with [Good First Issue](https://github.com/storybookjs/react-native/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) when we think they are well suited for people who are new to the codebase or OSS in general.
  285. - [Talk to us](https://discord.gg/sMFvFsG), we'll find something to suits your skills and learning interest.
  286. ## Examples
  287. Here are some example projects to help you get started
  288. - A mono repo setup by @axeldelafosse https://github.com/axeldelafosse/storybook-rnw-monorepo
  289. - Expo setup https://github.com/dannyhw/expo-storybook-starter
  290. - React Native CLI setup https://github.com/dannyhw/react-native-storybook-starter
  291. - Adding a separate entry point and dev menu item in native files for RN CLI project: https://github.com/zubko/react-native-storybook-with-dev-menu
  292. - Re.Pack setup https://github.com/dannyhw/RepackStorybookStarter
  293. - Want to showcase your own project? open a PR and add it to the list!
  294. ## Agent skills
  295. This repo includes agent skills for setting up and working with Storybook for React Native.
  296. ### Skills
  297. - **writing-react-native-storybook-stories** - Guides Claude on writing stories using Component Story Format (CSF), including controls, addons, decorators, parameters, and portable stories
  298. - **setup-react-native-storybook** - Guides Claude through adding Storybook to your project, covering Expo, Expo Router, React Native CLI, and Re.Pack setups
  299. - **upgrading-react-native-storybook** - Guides Claude through incremental React Native Storybook upgrades, split by supported migration paths from 5.3.x through 10.x, including converting remaining `storiesOf` stories to CSF during the 6.5.x to 7.6.x migration
  300. ### Installation
  301. #### Any AI agent or IDE (universal)
  302. ```sh
  303. npx skills add storybookjs/react-native
  304. ```
  305. This works with any agent harness that supports skills (Claude Code, Cursor, Windsurf, etc.).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.