feat: update documentation for entry-point swapping and deviceAddons#877
Open
ndelangen wants to merge 16 commits intocopilot/add-entry-point-swapping-storybookfrom
Open
feat: update documentation for entry-point swapping and deviceAddons#877ndelangen wants to merge 16 commits intocopilot/add-entry-point-swapping-storybookfrom
ndelangen wants to merge 16 commits intocopilot/add-entry-point-swapping-storybookfrom
Conversation
- Added a note in MANUAL_SETUP.md to clarify that the guide is for v8 and provided a link to v10 setup instructions. - Enhanced MIGRATION.md with detailed steps for migrating to the new `deviceAddons` property and entry-point swapping introduced in v10.4. - Updated README.md to reflect changes in bundler configuration and removed outdated instructions regarding app entry point modifications. - Revised various documentation files to emphasize the use of `deviceAddons` for on-device addons and the benefits of the bundler-agnostic `withStorybook` wrapper. All documentation updates aim to improve clarity and guide users through the new setup processes effectively.
|
- Consolidated the representation of `deviceAddons` in various configuration files, ensuring consistency across `MIGRATION.md`, `README.md`, and setup guides. - Removed unnecessary line breaks for improved readability in code examples. - Added clarifying notes in documentation regarding the use of `deviceAddons` for on-device addons, enhancing user understanding of the new setup. These changes aim to provide clearer guidance and a more cohesive experience for users transitioning to the updated configuration.
There was a problem hiding this comment.
Pull request overview
Updates the React Native Storybook documentation to present v10.4’s recommended “entry-point swapping” setup (@storybook/react-native/withStorybook) and to document the new deviceAddons config property for on-device addons.
Changes:
- Add new docs pages for migrating to entry-point swapping and for supported environment variables.
- Update Getting Started + configuration docs to recommend the bundler-agnostic
withStorybookwrapper and env-var-driven enabling. - Update addon docs and examples to recommend
deviceAddons(with backwards-compat guidance).
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/docs/intro/getting-started/repack.md | Adds a tip pointing Re.Pack users to the bundler-agnostic wrapper as an alternative. |
| docs/docs/intro/getting-started/migrating-to-entry-point-swapping.md | New migration guide covering bundler config, App.tsx cleanup, deviceAddons, scripts, and WebSocket guidance. |
| docs/docs/intro/getting-started/manual-setup.md | Updates manual setup to use the bundler-agnostic wrapper + deviceAddons, and reframes in-app integration as an alternative. |
| docs/docs/intro/getting-started/index.md | Updates the primary setup flow to use the bundler-agnostic wrapper and env-var-driven startup. |
| docs/docs/intro/getting-started/expo-router.md | Updates Expo Router guide with an entry-point swapping tip and new import path. |
| docs/docs/intro/configuration/websocket-configuration.md | Restructures WebSocket docs with the bundler-agnostic wrapper as primary guidance. |
| docs/docs/intro/configuration/metro-configuration.md | Clarifies Metro-specific wrapper vs recommended bundler-agnostic wrapper. |
| docs/docs/intro/configuration/index.md | Updates config overview, adds deviceAddons, and links to the new env vars page. |
| docs/docs/intro/configuration/environment-variables.md | New reference page for env vars supported by the bundler-agnostic wrapper. |
| docs/docs/intro/addons/index.md | Updates addon setup to use deviceAddons and explains why. |
| README.md | Updates root README setup instructions to recommended wrapper + deviceAddons, and revises “Hide/Show storybook” guidance. |
| MIGRATION.md | Adds v10 migration notes for deviceAddons and entry-point swapping. |
| MANUAL_SETUP.md | Adds a banner indicating this doc is for v8 and points to v10 docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+99
to
+104
| ### Override WebSocket host for physical devices | ||
|
|
||
| ```bash | ||
| STORYBOOK_ENABLED=true STORYBOOK_WS_HOST=192.168.1.100 STORYBOOK_WS_PORT=7007 expo start | ||
| ``` | ||
|
|
There was a problem hiding this comment.
STORYBOOK_WS_HOST=auto is documented here as a valid value, but the bundler-agnostic wrapper currently treats env vars as literal strings (no special-casing for auto) and passes host through to httpServer.listen(). Setting STORYBOOK_WS_HOST=auto will try to bind to hostname "auto" and is likely to fail. Consider removing auto from the env-var example and instead document websockets: 'auto' (if supported) or require an explicit IP/hostname in STORYBOOK_WS_HOST.
Member
Author
There was a problem hiding this comment.
@copilot STORYBOOK_WS_HOST=auto should just not be considered a valid use-case.
There was a problem hiding this comment.
Fixed in 01ab8d2.
I removed STORYBOOK_WS_HOST=auto usage from the docs examples and added explicit guidance that auto is not a valid value for STORYBOOK_WS_HOST.
Screenshot: /tmp/playwright-logs/page-2026-04-14T12-03-36-726Z.png
Comment on lines
+178
to
+180
| **Option B: Configure in metro config** | ||
|
|
||
| ```js |
There was a problem hiding this comment.
This example uses STORYBOOK_WS_HOST=auto, but the wrapper does not interpret auto specially when provided via env var (it’s treated as a literal hostname). This likely breaks startup because the channel server will try to bind to host "auto". Please update the example to use an explicit IP/hostname, or document websockets: 'auto' in config (if that’s the intended auto-detection mechanism).
Comment on lines
+23
to
35
| If you're using the bundler-agnostic `withStorybook` (from `@storybook/react-native/withStorybook`), WebSocket configuration is handled automatically. Pass `websockets: 'auto'` in your config or set environment variables: | ||
|
|
||
| ```js | ||
| // metro.config.js | ||
| const { withStorybook } = require('@storybook/react-native/metro/withStorybook'); | ||
| const { withStorybook } = require('@storybook/react-native/withStorybook'); | ||
|
|
||
| module.exports = withStorybook(config, { | ||
| websockets: { | ||
| port: 7007, | ||
| host: 'localhost', | ||
| }, | ||
| websockets: 'auto', | ||
| }); | ||
| ``` | ||
|
|
||
| ## Configuration Options | ||
| The wrapper auto-detects your LAN IP, starts the WebSocket server, and injects the connection settings into the generated `storybook.requires` file — no manual matching needed in `getStorybookUI`. | ||
|
|
There was a problem hiding this comment.
This section states that the bundler-agnostic wrapper handles WebSockets automatically and that websockets: 'auto' will auto-detect LAN IP, start the WebSocket server, and inject settings into storybook.requires. In the current implementation of @storybook/react-native/withStorybook, WebSocket server enablement is gated on a resolved host value (it uses websockets: Boolean(websockets.host)), so websockets: 'auto' does not actually enable WebSockets or inject connection settings unless a host is explicitly set. The docs should either (a) describe the current requirement to set STORYBOOK_WS_HOST / websockets.host, or (b) adjust code in a follow-up PR and keep docs in sync.
docs/docs/intro/getting-started/migrating-to-entry-point-swapping.md
Outdated
Show resolved
Hide resolved
Comment on lines
349
to
355
|
|
||
| Use `'auto'` to automatically detect your LAN IP and inject host/port into the generated `storybook.requires` file. | ||
|
|
||
| ### websockets.host | ||
| 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. | ||
|
|
||
| Type: `string`, default: `'localhost'` | ||
|
|
||
| The host on which to run the WebSocket, if specified. | ||
|
|
||
| ### websockets.port | ||
|
|
||
| Type: `number`, default: `7007` | ||
|
|
||
| The port on which to run the WebSocket, if specified. | ||
|
|
||
| ### websockets.secured | ||
|
|
||
| Type: `boolean`, default: `false` | ||
|
|
||
| When `true`, the channel server starts on `https` and upgrades WebSocket clients over `wss`. | ||
|
|
||
| ### websockets.key / websockets.cert | ||
|
|
||
| Type: `string | Buffer`, default: `undefined` | ||
|
|
||
| TLS private key and certificate used when `secured` is `true`. | ||
| > **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. | ||
|
|
||
| ## getStorybookUI options | ||
|
|
There was a problem hiding this comment.
The README states that websockets: 'auto' will auto-detect LAN IP and inject host/port into storybook.requires, and that env vars can override those settings. In the current @storybook/react-native/withStorybook implementation, WebSockets/injection are only enabled when a host is present, so 'auto' doesn’t actually trigger WebSocket enablement/injection on its own. Please update this doc to reflect the current behavior (require explicit host) or align the implementation in a follow-up PR.
Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/d3d2217a-7248-48a9-a110-5fe72bae5bf2 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com>
…point-swapping-docs
- Revised the guide to clarify the setup of Storybook as a route within an Expo Router app, emphasizing the benefits of entry-point swapping. - Updated Metro configuration instructions to use the Metro-specific `withStorybook` wrapper, ensuring proper integration without entry-point swapping. - Enhanced navigation setup details for accessing Storybook within the app, including recommendations for disabling headers for a better user experience. - Added tips and warnings to guide users on the preferred setup methods and potential pitfalls. These changes aim to improve clarity and usability for developers integrating Storybook with Expo Router.
- Updated the Re.Pack setup documentation to clarify the differences when using Rspack/Webpack instead of Metro, emphasizing the bundler-agnostic `withStorybook` wrapper. - Streamlined installation instructions and entry-point swapping details, ensuring users understand the necessary configurations for Rspack. - Added warnings regarding the `enablePackageExports` requirement for proper package resolution and clarified the in-app integration process using the `StorybookPlugin`. These changes aim to enhance clarity and usability for developers integrating Storybook with Re.Pack projects.
- Revised the documentation to clarify that `.rnstorybook/index.tsx` must register a root component when Storybook is enabled. - Added detailed code examples for setting up the entry point correctly, ensuring users understand the necessary changes. - Updated subsequent steps to reflect the new structure and improved clarity on managing on-device addons and script updates. These changes aim to enhance the user experience and provide clear guidance for developers integrating Storybook with their applications.
- Updated the documentation to clarify the use of the bundler-agnostic `withStorybook` wrapper as the recommended approach for new projects. - Enhanced the explanation of configuration options, including environment variables and their precedence over wrapper options. - Streamlined the sections on basic usage and options for both the bundler-agnostic and Metro-specific wrappers, improving clarity and usability for developers. These changes aim to provide clearer guidance for integrating Storybook with Metro projects.
- Removed redundant export statements for `StorybookUIRoot` across multiple sections to streamline the code examples. - Updated the WebSocket options section to clarify the auto-injection of settings when using the `withStorybook` wrapper. - Added a new subsection for testing setup with WebSocket control, providing clearer instructions for users on configuring their environments. These changes aim to improve clarity and usability for developers integrating Storybook with their applications.
- Updated the CLI configuration documentation to emphasize that the `sb-rn-get-stories` command is only necessary for custom build pipelines without the `withStorybook` wrapper. - Added a note highlighting that the `storybook.requires.ts` file is automatically generated when using the recommended setup, reducing the need for manual CLI commands. - Streamlined sections on when the CLI is needed, improving clarity for users on integrating Storybook with their applications. These changes aim to enhance user understanding and streamline the setup process for developers.
…dons - Replaced references to `addons` with `deviceAddons` across multiple documentation files, including setup guides and README files for on-device addons. - Clarified instructions for integrating on-device addons in the Storybook configuration, ensuring consistency and accuracy in the setup process. - Enhanced user understanding of the new configuration structure, promoting best practices for integrating Storybook with React Native applications. These changes aim to improve clarity and usability for developers transitioning to the updated addon configuration.
- Changed code snippets in the WebSocket configuration documentation from JavaScript to TypeScript for consistency and clarity. - Updated various sections to reflect the correct syntax and improve readability, ensuring users have accurate examples for integrating WebSocket with Storybook. - Enhanced the overall documentation to better support developers using TypeScript in their projects. These changes aim to improve the developer experience and provide clearer guidance for WebSocket integration in Storybook.
- Clarified the process for regenerating the `storybook.requires.ts` file after modifying `main.ts`, emphasizing the automatic regeneration when using the `withStorybook` wrapper. - Added a detailed note for users not utilizing the `withStorybook` wrapper, providing manual regeneration instructions. - Improved overall clarity and usability of the documentation for configuring backgrounds in Storybook. These changes aim to enhance the developer experience and ensure accurate guidance for background configuration.
- Changed code snippet formatting from `bash` to `sh` for consistency across environment variable examples. - Ensured clarity in the usage of environment variables related to Storybook configuration, enhancing readability and usability for developers. - Aimed to provide accurate and uniform documentation for setting up Storybook with various environment variables. These changes improve the overall developer experience by standardizing code examples in the documentation.
- Updated all code snippets in the documentation from `typescript` to `ts` for consistency across various files, including migration, development workflows, testing, and configuration sections. - Enhanced readability and uniformity in the documentation, ensuring a better developer experience when referencing code examples. These changes aim to improve clarity and maintain a consistent style throughout the documentation.
- Updated all code snippets in the documentation from `bash` to `sh` for consistency across various files, including setup guides, configuration, and usage instructions. - Enhanced readability and uniformity in the documentation, ensuring a better developer experience when referencing code examples. These changes aim to improve clarity and maintain a consistent style throughout the documentation.
ndelangen
added a commit
that referenced
this pull request
Apr 14, 2026
…mment) - Updated the condition to disable experimental MCP settings when the server is not present, ensuring proper configuration behavior. - This change enhances the reliability of the withStorybook function in various environments. All tests pass successfully.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the Easy React Native Setup project — specifically M5: Update documentation.
Stacks on #871 (bundler-agnostic
withStorybookwrapper +deviceAddonsruntime).Companion to storybookjs/storybook#34333 (CLI init overhaul, codemods, automigrations).
Summary
Rewrites the documentation across the docs site, README, and migration guides to reflect two v10.4 features introduced in #871:
Entry-point swapping — The new bundler-agnostic
withStorybookwrapper (@storybook/react-native/withStorybook) is now the recommended default. It auto-detects Metro vs Re.Pack, readsSTORYBOOK_ENABLEDfrom environment variables, and swaps the app entry point at the bundler level. No changes toApp.tsxrequired.deviceAddons— On-device addons now use a dedicateddeviceAddonsproperty inmain.tsinstead ofaddons, preventingCriticalPresetLoadErrorduring server-side operations likeextract(Split addons from "ondevice" addons inmain.ts#873). Theaddonsproperty still works —deviceAddonsis the recommended approach going forward.Editorial approach
App.tsx) is described as "fully supported" — not deprecated or legacywithStorybook(@storybook/react-native/metro/withStorybook) is also described as "fully supported" for projects needing direct Metro controlpackages/react-native/src/What changed
New pages
migrating-to-entry-point-swapping.mdApp.tsxrendering,addons→deviceAddons, update scripts, simplify WebSocket config, restart Metro. Includesnpx storybook automigratetip.environment-variables.mdSTORYBOOK_ENABLED,STORYBOOK_WS_HOST,STORYBOOK_WS_PORT,STORYBOOK_WS_SECURED,STORYBOOK_SERVER,STORYBOOK_DISABLE_UI.Updated pages
index.md)STORYBOOK_ENABLED=true. In-app integration in collapsible "Alternative" section.manual-setup.md)deviceAddonsinmain.ts.expo-router.md)repack.md)configuration/index.md)main.tsexamples usedeviceAddons, documents the property, links to env vars page.metro-configuration.md)websocket-configuration.md)addons/index.md)deviceAddonswith:::info Why deviceAddons?explainer.Updated root files
deviceAddonswith backwards-compat note.deviceAddonsand entry-point swapping (v10.4) subsections.M5 coverage vs tracking issue
Checking against the M5 checklist in #34276:
STORYBOOK_ENABLEDusage.rnstorybook/indexcustomizationgetStorybookUIcall, but there's no dedicated section on how to customize it (adding providers, setup code, theming). Could be a follow-up.migrating-to-entry-point-swapping.md— was a stretch goal, fully deliveredchromatic-clichanges that are still in progress. Should be tracked separately.Test plan
cd docs && pnpm build— verify no broken links or build errorswithStorybookwrapper for entrypoint-swapping #871cc @kylegach for docs review