feat: update documentation for entry-point swapping and deviceAddons

.claude/commands/pr-description.md

@@ -5,7 +5,7 @@ Generate a pull request description based on the changes in the current branch.
 ## Instructions
 
 1. First, determine the base branch by checking for a PR or using `next` as default:
-   ```bash
+   ```sh
    gh pr view --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "next"
    ```
 
@@ -23,7 +23,7 @@ Generate a pull request description based on the changes in the current branch.
    - Answer the template questions about examples and documentation
 
 5. Check if a PR exists for this branch:
-   ```bash
+   ```sh
    gh pr view --json number 2>/dev/null
    ```
 

CLAUDE.md

@@ -2,7 +2,7 @@ This file provides guidance to agents when working with code in this repository.
 
 ## Development Commands
 
-```bash
+```sh
 # Initial Setup
 pnpm install
 pnpm build

MANUAL_SETUP.md

@@ -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).
+
 Before getting into the guide consider using a template for a simpler setup process.
 
 **Prebuilt Templates:**
@@ -61,7 +63,7 @@ import type { StorybookConfig } from '@storybook/react-native';
 
 const main: StorybookConfig = {
   stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
-  addons: [],
+  deviceAddons: [],
 };
 
 export default main;

MIGRATION.md

@@ -206,23 +206,63 @@ The metro config (`enabled` flag) automatically handles bundle inclusion:
 
 After updating dependencies and configuration, regenerate your `.rnstorybook/storybook.requires.ts` file:
 
-```bash
+```sh
 yarn storybook-generate
 ```
 
 Or if you have the generate call in your metro config (recommended), just restart metro:
 
-```bash
+```sh
 yarn start --reset-cache
 ```
 
+### Move on-device addons to `deviceAddons`
+
+On-device addons should now be listed in the `deviceAddons` property instead of `addons` in your `.rnstorybook/main.ts`. This prevents errors during server-side operations like `extract`, where Storybook Core would try to evaluate React Native code as Node.js presets.
+
+**Before:**
+
+```ts
+const main: StorybookConfig = {
+  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
+  addons: ['@storybook/addon-ondevice-controls', '@storybook/addon-ondevice-actions'],
+};
+```
+
+**After:**
+
+```ts
+const main: StorybookConfig = {
+  stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
+  deviceAddons: ['@storybook/addon-ondevice-controls', '@storybook/addon-ondevice-actions'],
+};
+```
+
+For backwards compatibility, on-device addons in the `addons` array still work — they're detected by the "ondevice" substring in their name. If you're using the Storybook CLI, the `rn-ondevice-addons-to-device-addons` automigration handles this step automatically.
+
+### Entry-point swapping (new in v10.4)
+
+v10.4 introduces a new bundler-agnostic `withStorybook` wrapper that handles entry-point swapping automatically. Instead of importing Storybook in your `App.tsx`, you set `STORYBOOK_ENABLED=true` and the wrapper swaps your app's entry point with Storybook's entry point at the bundler level.
+
+```js
+// metro.config.js — new recommended import
+const { withStorybook } = require('@storybook/react-native/withStorybook');
+
+module.exports = withStorybook(config);
+```
+
+Then run with `STORYBOOK_ENABLED=true expo start`. No changes to `App.tsx` needed.
+
+This is the recommended approach for new projects. Existing projects can migrate at their own pace — see [Migrating to Entry-Point Swapping](https://storybookjs.github.io/react-native/docs/intro/getting-started/migrating-to-entry-point-swapping) for a step-by-step guide.
+
 ### Summary of breaking changes
 
 1. **Metro config API changes:**
    - **BREAKING:** `withStorybook` is now a named export - use `const { withStorybook } = require(...)` instead of default import
    - `withStorybookConfig` from `metro/withStorybookConfig` is removed
    - Use `withStorybook` from `metro/withStorybook` instead (the simplified API is now standard)
    - `onDisabledRemoveStorybook` option removed (automatic when `enabled: false`)
+   - **New (v10.4):** Bundler-agnostic `withStorybook` from `@storybook/react-native/withStorybook` (auto-detects Metro/Re.Pack, env-var driven)
 
 2. **Default config folder:**
    - Confirmed as `./.rnstorybook` (to avoid conflicts with web Storybook)
@@ -232,7 +272,12 @@ yarn start --reset-cache
 
 4. **Simplified app entry:**
    - Custom switcher components no longer needed for bundle optimization
-   - Metro config handles conditional inclusion automatically
+   - Entry-point swapping (v10.4): bundler swaps app entry for Storybook entry when `STORYBOOK_ENABLED=true`
+   - In-app integration (importing Storybook in App.tsx) continues to work and is fully supported
+
+5. **`deviceAddons` property:**
+   - On-device addons should use the new `deviceAddons` property in `main.ts`
+   - Backwards compatible — `addons` still works for on-device addons
 
 ## From version 8 to 9
 
@@ -458,7 +503,7 @@ We've removed the types from `@storybook/react-native` and now you should import
 
 Heres an example story in version 7:
 
-```typescript
+```ts
 import type { Meta, StoryObj } from '@storybook/react';
 import { Button } from './Button';
 
@@ -482,13 +527,13 @@ export const Basic: Story = {
 
 You can now also update main.js to main.ts and use the StorybookConfig type. This is one of the only types we export from @storybook/react-native in this version.
 
-```typescript
+```ts
 // .storybook/main.ts
 import type { StorybookConfig } from '@storybook/react-native';
 
 const main: StorybookConfig = {
   stories: ['../components/**/*.stories.?(ts|tsx|js|jsx)'],
-  addons: [
+  deviceAddons: [
     '@storybook/addon-ondevice-notes',
     '@storybook/addon-ondevice-controls',
     '@storybook/addon-ondevice-backgrounds',
@@ -501,7 +546,7 @@ export default main;
 
 To update preview.js to preview.tsx you can use the Preview type from @storybook/react
 
-```typescript
+```ts
 import type { Preview } from '@storybook/react';
 
 const preview: Preview = {
@@ -540,7 +585,7 @@ The setup is the same as `@storybook/addon-react-native-web` but with the reactN
 
 #### First install necessary packages
 
-```bash
+```sh
 yarn add -D @storybook/addon-react-native-web @storybook/addon-essentials storybook @storybook/react-webpack5 @storybook/react babel-plugin-react-native-web react-native-web @storybook/addon-react-native-server
 ```
 
@@ -557,7 +602,7 @@ With expo you should also add `@expo/metro-runtime`.
 
 Add a `main.ts`
 
-```typescript
+```ts
 // .storybook-web/main.ts
 import type { StorybookConfig } from '@storybook/react-webpack5';