feat: update documentation for entry-point swapping and deviceAddons#877
Merged
ndelangen merged 24 commits intocopilot/add-entry-point-swapping-storybookfrom May 4, 2026
Merged
Conversation
|
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
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.
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.
6 tasks
Member
Author
|
@dannyhw Do these documentation changes all look correct to you? |
8 tasks
dannyhw
reviewed
May 2, 2026
Member
There was a problem hiding this comment.
probably don't need to update the blog file as its not a documentation exactly
- 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.
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>
- 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.
Clarified the section title and improved the explanation for the WebSocket-controlled testing setup.
dannyhw
force-pushed
the
entry-point-swapping-docs
branch
from
e52d775 to
d3f361d
Compare
Member
|
rebased to resolve conflicts |
Member
|
feedback for future prs: changing all the |
dannyhw
reviewed
May 2, 2026
dannyhw
reviewed
May 2, 2026
dannyhw
reviewed
May 2, 2026
dannyhw
reviewed
May 2, 2026
| The `declare const` tells TypeScript about the global that Rspack's `DefinePlugin` injects. When `STORYBOOK_ENABLED` is `false`, Rspack dead-code-eliminates the Storybook branch entirely. | ||
|
|
||
| ## Add Scripts | ||
| For the rest of the setup (`.rnstorybook` folder, dependencies, running scripts), follow the [Manual Setup](./manual-setup.md) guide — everything except the bundler config is identical. |
Member
There was a problem hiding this comment.
Is it really necessary to do this? theres just one small bit of package.json left in the guide
Member
Author
There was a problem hiding this comment.
What would you suggest instead?
dannyhw
reviewed
May 2, 2026
| @@ -1,5 +1,7 @@ | |||
| # Setup for v8 React Native Storybook | |||
|
|
|||
| > **This guide is for v8.** For v10 manual setup instructions, see the [manual setup docs](https://storybookjs.github.io/react-native/docs/intro/getting-started/manual-setup). | |||
Member
There was a problem hiding this comment.
if this is the case why don't we just replace the whole guide here with a link to the docs? potentially the title about it being v8 is just outdated?
Member
Author
There was a problem hiding this comment.
I'm unsure how to address this feedback. Can you propose a solution, @dannyhw ?
Member
There was a problem hiding this comment.
honestly probably just remove this document and replace links to it with a link to the guide in the docs
dannyhw
reviewed
May 2, 2026
dannyhw
reviewed
May 2, 2026
- Revised the migration guide to reflect changes from version 10.3 to 10.4, including updates to the metro configuration and the introduction of entry-point swapping. - Added instructions for migrating to the new `deviceAddons` property and clarified the process for updating Storybook dependencies. - Enhanced clarity and usability of the documentation to support developers transitioning to the latest version of Storybook.
- Eliminated the outdated `addons` section in the Storybook configuration documentation, focusing on the current `deviceAddons` usage. - Streamlined the content to enhance clarity and ensure users are directed towards the correct configuration practices for on-device addons. - Aimed to improve the overall documentation quality and developer experience by removing unnecessary information.
- Eliminated the export statement for `StorybookUIRoot` in the migration guide to align with the updated configuration practices. - This change simplifies the example and focuses on the registration of the component, enhancing clarity for developers migrating to entry-point swapping.
- Enhanced the `withStorybook` export to include a configuration object, allowing for custom `configPath` and WebSocket settings. - Improved clarity on the new configuration capabilities, emphasizing the automatic detection of Metro or Re.Pack usage. - Aimed to streamline the migration process for developers transitioning to the latest Storybook practices.
- Cleaned up the migration guide by removing an unnecessary empty line, improving the overall formatting and readability of the document. - This minor edit contributes to a more polished presentation of the migration instructions for developers transitioning between Storybook versions.
ndelangen
commented
May 4, 2026
- Included a missing code block in the repack documentation to enhance clarity and provide a complete example for users. - This addition aims to improve the overall usability of the documentation for developers getting started with Re.Pack.
dannyhw
approved these changes
May 4, 2026
ndelangen
merged commit 7960793
into
copilot/add-entry-point-swapping-storybook
1 check passed
ndelangen
added a commit
that referenced
this pull request
May 5, 2026
* Initial plan * feat: add entry-point swapping, resolveEntryPoint, and websocket env overrides to withStorybook M4 implementation: - Add resolveEntryPoint() to detect app entry (Expo, Expo Router, RN CLI) - Add entry-point swapping in resolver when STORYBOOK_ENABLED=true - Add websocket env variable overrides (STORYBOOK_WS_HOST/PORT/SECURED) - Add comprehensive tests for all new functionality Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/58a5fb17-1ee3-4e0b-ae60-aee474de2d32 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: address code review feedback - use os.tmpdir() and reduce syscalls Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/58a5fb17-1ee3-4e0b-ae60-aee474de2d32 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * feat: split withStorybook into backwards-compat and entry-swap wrappers - Restore withStorybook to original behavior (no entry-point swapping, no ws env overrides) - Create withStorybookSwap with entry-point swapping + ws env overrides - Export shared utilities (resolveEntryPoint, resolveFileWithExtensions, resolveStorybookEntry, applyWebsocketEnvOverrides) from withStorybook.ts - Add metro/withStorybookSwap.js re-export and package.json export path - Add withStorybookSwap to tsup build entries - Tests: 33 passing across 5 suites Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/a3213ee7-9a44-4b9a-a4b2-f434af51c3ce Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: remove unnecessary re-exports from withStorybookSwap Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/a3213ee7-9a44-4b9a-a4b2-f434af51c3ce Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * feat: add unified withStorybook<T> wrapper at @storybook/react-native/withStorybook Creates a bundler-agnostic withStorybook<T>(config: T, options?): T that auto-detects Metro vs Repack and delegates accordingly: - Metro: entry-point swapping + ws env overrides (via withStorybookSwap) - Repack: adds StorybookPlugin with ws env overrides to plugins array This allows sb init to always generate the same config regardless of bundler. Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/e08bd14d-760c-471e-938c-e26d89e9ae9b Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: rename rspackConfig to bundlerConfig for clarity Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/e08bd14d-760c-471e-938c-e26d89e9ae9b Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: restore metro/withStorybook.ts to original, move shared utilities to utils.ts metro/withStorybook.ts and repack/withStorybook.ts are now completely untouched from the original codebase. Shared utilities (resolveEntryPoint, applyWebsocketEnvOverrides, etc.) moved to src/metro/utils.ts. Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/ff97ee2b-2851-4e59-a8bf-d851bc4ac5a0 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: remove ./metro/withStorybookSwap from public exports withStorybookSwap is an internal implementation detail. Only ./withStorybook is the new public export. Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/612826f0-d034-4523-acb6-b19af165b1b3 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * chore: add changeset for unified withStorybook wrapper (minor) Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/bcec5c8e-36b0-49da-883e-f1c6b5fd730d Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: restructure withStorybook architecture per review feedback - Early return in withStorybook when STORYBOOK_ENABLED is not set - withStorybook loads all env vars and passes resolved data to enhancers - Rename withStorybookSwap → enhanceMetroConfig (better naming, new location) - Create enhanceRepackConfig (separate internal enhancer) - Reduce JSDoc bloat on internal functions - Enhancers act solely on passed-in data (easy to test) - 40 tests across 8 suites all passing Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/b83cdef6-b12b-4de9-a962-5f9bdbf9e8fa Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * style: use top-level import for WebsocketsOptions in utils.ts Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/b83cdef6-b12b-4de9-a962-5f9bdbf9e8fa Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: remove legacy baseWithStorybook dependency from enhanceMetroConfig enhanceMetroConfig now implements its own Metro config enhancement directly (generate, createChannelServer, resolver, transformer) instead of delegating to the legacy metro/withStorybook wrapper. All 40 tests pass across 8 suites. Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/f5abdf02-6a43-4724-bd23-02a984598b50 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: rewrite enhanceRepackConfig to implement entry-point swapping independently - enhanceRepackConfig no longer uses legacy StorybookPlugin - It only swaps the config's entry field when swap data is provided - generate() and createChannelServer() moved to withStorybook for the Repack path - All 40 tests pass across 8 suites Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/69a23616-1b5b-4c75-8663-a75b0a42bff8 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: move shared setup (generate, createChannelServer) from enhanceMetroConfig into withStorybook Both Metro and Repack paths now share the same generate() and createChannelServer() setup in withStorybook. enhanceMetroConfig only handles Metro-specific config (transformer + resolver). All 40 tests pass. Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/7668916d-f64d-46a2-adfd-af57da5265d2 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: merge swap into options argument for both enhancers Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/b36857dd-c7e3-44d1-af38-87dbd52e8ea8 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * feat: add liteMode option to enhanceRepackConfig and improve environment variable handling in withStorybook - Introduced optional liteMode parameter in EnhanceRepackOptions interface. - Enhanced environment variable processing functions for better clarity and reusability. - Updated withStorybook to utilize new environment variable functions and handle liteMode configuration. All tests pass successfully. * feat: add TODO for liteMode support in enhanceRepackConfig - Added a TODO comment to indicate future support for liteMode in enhanceRepackConfig. - This prepares the codebase for upcoming enhancements related to liteMode functionality. * feat: implement liteMode support in enhanceRepackConfig Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/34a3036a-1f92-48b6-8123-9e4ee876fdea Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: remove unnecessary type casts in enhanceRepackConfig Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/34a3036a-1f92-48b6-8123-9e4ee876fdea Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * remove enhanceMetroConfig and enhanceRepackConfig from tsup entrypoints (internal-only modules) Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/4412b548-bfa3-4ace-bfbc-6e3117407aae Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * refactor: clean up code formatting and type casting in configuration files - Removed unnecessary line breaks in enhanceMetroConfig.test.ts and utils.test.ts for improved readability. - Updated type casting in enhanceRepackConfig.ts to use 'as T' for better type safety. - Removed baseUrl from tsconfig.json as it was not needed. All tests pass successfully. * feat: add liteMode support to generate function and update related configurations - Introduced liteMode parameter in the generate function to enhance flexibility. - Updated enhanceMetroConfig and enhanceRepackConfig to remove liteMode handling, streamlining the configuration process. - Modified View class to accommodate options, including liteMode, for improved UI behavior. - Ensured compatibility with existing functionality while preparing for future enhancements. All tests pass successfully. * fix: update View instantiation to include options parameter - Modified the View class instantiation in Start.tsx to accept an options parameter, enhancing flexibility for future configurations. - This change aligns with recent updates to support additional options in the View class. All tests pass successfully. * feat: enhance View component with SafeArea support and update generate function - Integrated SafeAreaView and StatusBar into the View component for improved UI layout and safety on different devices. - Updated the generate function to ensure reactNativeOptions defaults to an empty object, enhancing robustness in configuration handling. All tests pass successfully. * test: remove liteMode tests from enhancers (liteMode moved to generate function) Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/359b24b6-6adf-4735-8775-90f06017b071 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * test: update generate.test.ts snapshots to match current generate.js output Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/4aefe5ff-32fe-44ee-b1ef-433fea6c580d Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * feat: add `deviceAddons` property to separate on-device addons from core addons (#874) * feat: add deviceAddons property for on-device addons separation - Add `deviceAddons` to `StorybookConfig` type - Update `generate.js` to merge addons from both `addons` and `deviceAddons` - Update init template to use `deviceAddons` for on-device addons - Update expo-example to use `deviceAddons` - Add tests for deviceAddons and mixed addons scenarios - Backwards compatible: addons in `addons` field still work Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/82703242-efa9-4fae-8cca-c667593bb37f Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * chore: add changeset for deviceAddons feature Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/b99f73e3-2330-42e2-8149-ab13e5f3892c Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: update deviceAddons test snapshots after base branch merge Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/0102d455-cd0f-430c-bab9-f3921b3ad9b8 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> Co-authored-by: Norbert de Langen <ndelangen@me.com> * refactor: improve logging and update liteMode handling in View and withStorybook - Enhanced logging in the View component to provide clearer output when a persisted story is not found. - Updated the handling of the liteMode option in withStorybook to use a new environment variable for better configuration management. All tests pass successfully. * make storage optional, never throw * feat: add WebSocket smoke server and environment variable support for Storybook - Introduced a minimal WebSocket server for manual connectivity checks, configurable via environment variables `STORYBOOK_WS_HOST`, `STORYBOOK_WS_PORT`, and `STORYBOOK_WS_SECURED`. - Updated `withStorybook` and `withStorybook.test.ts` to utilize these environment variables for improved configuration management. - Enhanced the handling of WebSocket options to allow for dynamic binding based on environment settings. All tests pass successfully. * chore: update package.json files across multiple packages - Reorganized scripts in package.json files to improve consistency and clarity, including the addition of `check:types` and reordering of existing scripts. - Updated dependencies and added missing fields such as `license` and `files` in several package.json files. - Enhanced the handling of `deviceAddons` in the configuration files to ensure proper migration warnings for legacy usage. - Added new test cases to validate the migration of on-device addons and ensure backward compatibility. All tests pass successfully. * refactor: deprecate `addons` field in Storybook configuration - Updated the `StorybookConfig` interface to mark the `addons` field as deprecated, advising users to migrate to `deviceAddons`. - Enhanced the `generate.js` script to log a deprecation warning when `addons` is used, guiding users to move their entries to `deviceAddons`. - Adjusted tests to verify the deprecation warning functionality for non-empty `addons`. All tests pass successfully. * fix: correct server condition in withStorybook function, see #877 (comment) - 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. * style: format code for better readability in generate.js - Adjusted the formatting of the `names` variable declaration for improved clarity. - This change enhances the overall readability of the script without altering its functionality. All tests pass successfully. * fix: import StatusBar in View component for proper functionality - Added the `StatusBar` import to the `View.tsx` file to ensure the component can utilize the status bar features as intended. - This change is necessary for maintaining the expected behavior of the View component in the application. All tests pass successfully. * style: simplify logging condition in View component - Refactored the logging condition in the View component to improve code readability by removing unnecessary braces. - This change maintains the existing functionality while enhancing the clarity of the code. All tests pass successfully. * fix: update storage prop in View component for consistency - Changed the storage prop in the View component to use the local variable instead of the class property, ensuring consistency in the component's behavior. - This update improves the clarity of the code and aligns with best practices for prop usage. All tests pass successfully. * fix: ensure secured option defaults to false in withStorybook function - Updated the withStorybook function to set the secured option to false by default when websockets.secured is undefined. This change improves the reliability of the WebSocket configuration. - All tests pass successfully. * refactor: enhance generate function parameter structure and improve host handling - Updated the `generate` function to use a structured options parameter, improving clarity and maintainability. - Simplified the host handling logic in the `withStorybook` function for better readability. - These changes enhance the overall code quality while maintaining existing functionality. All tests pass successfully. * refactor: improve WebSocket handling in withStorybook function - Refactored the WebSocket configuration logic in the withStorybook function to enhance clarity and maintainability. - Introduced new variables for resolved WebSocket options, simplifying the handling of host and port settings. - Updated the generate function call to conditionally include WebSocket parameters based on the new structure. All tests pass successfully. * refactor: rename options parameter in generate function for clarity - Updated the `generate` function to rename the `options` parameter to `generateOptions`, enhancing code readability and clarity. - This change aligns with the structured parameter approach established in previous commits, improving maintainability. All tests pass successfully. * style: fix formatting in package.json and withStorybook.ts - Added a newline at the end of package.json for consistency with file formatting standards. - Simplified the formatting of WebSocket handling conditions in withStorybook.ts for improved readability without changing functionality. All tests pass successfully. * feat: add environment variable utility functions for better configuration handling - Introduced new utility functions in env-tools.ts to convert environment variables to boolean, string, and number types, enhancing configuration management. - Updated withStorybook.ts and related files to utilize these new functions, improving code clarity and reducing redundancy. All tests pass successfully. * refactor: update generate function and WebSocket handling in withStorybook - Renamed the `liteMode` option to `disableUI` in the `generate` function and updated related logic for clarity. - Introduced a new `loadWebsocketEnvOverrides` function in `env-tools.ts` to streamline WebSocket configuration handling. - Refactored `withStorybook` to utilize the new WebSocket loading function, improving code organization and maintainability. All tests pass successfully. * feat: add disableUI option to enhance configuration flexibility - Introduced a new `disableUI` option in the `ReactNativeOptions` and `WithStorybookOptions` interfaces to provide additional control over UI behavior. - Updated the `View` component to utilize the `disableUI` option, modifying the logic for `onDeviceUI` and `shouldPersistSelection` accordingly. All tests pass successfully. * fix: check params.storage in warning condition to avoid unreachable code Agent-Logs-Url: https://github.com/storybookjs/react-native/sessions/d02c8d49-63e9-4f39-8100-da83eff9ff85 Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> * fix: handle 'tty' and 'os' module resolution in enhanceMetroConfig - Updated the enhanceMetroConfig function to return an empty type for 'tty' and 'os' module requests, preventing potential resolution issues. - This change improves compatibility and stability in module resolution without altering existing functionality. All tests pass successfully. * sort package.json files * delete * fix: update deprecation warning for addons field in generate.js - Modified the warning message to clarify that entries in the `addons` field should be moved to `deviceAddons`, emphasizing that they will not be evaluated as Storybook Core presets. - Removed redundant text for improved readability. This change aims to enhance user understanding of the deprecation notice. * fix: add missing newline at end of package.json files - Ensured that both `package.json` files in the root and `react-native` package have a newline at the end of the file for better compatibility with various tools and standards. * fix: enhance withStorybook function to support options.enabled - Updated the withStorybook function to allow the enabled state to be determined by options.enabled, providing greater flexibility in configuration. - This change ensures that the function behaves correctly based on the provided options, improving usability for developers. * refactor: streamline main config file loading in generate.js - Replaced multiple checks for different main config file types (main.ts, main.js, main.cjs) with a single call to getInterpretedFile, simplifying the logic and improving maintainability. - Updated error handling to provide clearer feedback when the main config file is not found. * chore: remove unused ws-smoke-server script and clean up package.json - Deleted the ws-smoke-server.mjs script as it was no longer needed. - Removed the corresponding entry from package.json to streamline the configuration. * fix: handle optional options parameter in View constructor - Updated the View constructor to default the options parameter to an empty object if not provided, ensuring better handling of undefined values. - Modified the onDeviceUI assignment to use optional chaining for improved safety when accessing properties on the options object. * feat: add liteMode option to enhanceMetroConfig and enhanceRepackConfig - Introduced a new optional `liteMode` parameter to both enhanceMetroConfig and enhanceRepackConfig, allowing the removal of the default Storybook UI from the bundle. - Updated the withStorybook function to pass the liteMode option, ensuring consistent behavior across configurations. - Enhanced the logic to conditionally handle the presence of the liteMode option in both configurations. * add example for testing new wrapper with expo * fix: add missing newlines at the end of JSON files and clean up imports in storybook.requires.ts - Added missing newlines at the end of package.json files in various directories to adhere to formatting standards. - Cleaned up import statements in storybook.requires.ts for consistency and readability. * some small fixes * fix: should maintain fix for expo router in enchance metro config * ignore requires in prettier * add expo router example * fix: expo router resolution * fix formatting * fix: test * add way to opt out of safearea * remove unused import * fix: use withstorybook wrapper for repack too * feat: update documentation for entry-point swapping and deviceAddons (#877) * feat: update documentation for entry-point swapping and deviceAddons - 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. * refactor: streamline documentation and code for deviceAddons - 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. * docs: remove STORYBOOK_WS_HOST=auto usage from env var examples 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> * docs: update Expo Router setup for Storybook integration - 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. * docs: revise Re.Pack setup guide for Storybook integration - 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. * docs: update entry-point swapping instructions for Storybook integration - 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. * docs: refine Metro configuration documentation for Storybook integration - 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. * docs: enhance Storybook UI configuration documentation - 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. * docs: clarify CLI configuration for Storybook integration - 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. * docs: update documentation to reflect changes from addons to deviceAddons - 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. * docs: update WebSocket configuration examples to TypeScript - 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. * docs: update backgrounds configuration instructions - 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. * docs: update environment variable documentation for Storybook - 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. * docs: standardize code snippet formatting to TypeScript - 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. * docs: standardize code snippet formatting to shell - 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. * copy edits * Update section title and clarify WebSocket testing setup Clarified the section title and improved the explanation for the WebSocket-controlled testing setup. * docs: update migration guide for Storybook version 10.4 - Revised the migration guide to reflect changes from version 10.3 to 10.4, including updates to the metro configuration and the introduction of entry-point swapping. - Added instructions for migrating to the new `deviceAddons` property and clarified the process for updating Storybook dependencies. - Enhanced clarity and usability of the documentation to support developers transitioning to the latest version of Storybook. * docs: remove deprecated addons section from configuration documentation - Eliminated the outdated `addons` section in the Storybook configuration documentation, focusing on the current `deviceAddons` usage. - Streamlined the content to enhance clarity and ensure users are directed towards the correct configuration practices for on-device addons. - Aimed to improve the overall documentation quality and developer experience by removing unnecessary information. * docs: remove export statement for StorybookUIRoot in migration guide - Eliminated the export statement for `StorybookUIRoot` in the migration guide to align with the updated configuration practices. - This change simplifies the example and focuses on the registration of the component, enhancing clarity for developers migrating to entry-point swapping. * docs: update withStorybook configuration in migration guide - Enhanced the `withStorybook` export to include a configuration object, allowing for custom `configPath` and WebSocket settings. - Improved clarity on the new configuration capabilities, emphasizing the automatic detection of Metro or Re.Pack usage. - Aimed to streamline the migration process for developers transitioning to the latest Storybook practices. * docs: remove empty line in migration guide for Storybook version updates - Cleaned up the migration guide by removing an unnecessary empty line, improving the overall formatting and readability of the document. - This minor edit contributes to a more polished presentation of the migration instructions for developers transitioning between Storybook versions. * Apply suggestion from @ndelangen * docs: add missing code block in repack documentation - Included a missing code block in the repack documentation to enhance clarity and provide a complete example for users. - This addition aims to improve the overall usability of the documentation for developers getting started with Re.Pack. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: winkerVSbecks <varunvachhar@gmail.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: ndelangen <3070389+ndelangen@users.noreply.github.com> Co-authored-by: Norbert de Langen <ndelangen@me.com> Co-authored-by: Daniel Williams <dannyhyunsoowilliams@gmail.com> Co-authored-by: Daniel Williams <me@dannyhw.com> Co-authored-by: winkerVSbecks <varunvachhar@gmail.com>
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