[$250] Storybook isn't working on dev

[roryabraham]

coming from #89424 (comment)

Problem

npm run storybook isn't working on dev.

Solution

Fix it

Issue Owner

Current Issue Owner: @shubham1206agra

Upwork Automation - Do Not Edit

• Upwork Job URL: https://www.upwork.com/jobs/~022051343848904319955
• Upwork Job ID: 2051343848904319955
• Last Price Increase: 2026-05-04

[melvin-bot]

Triggered auto assignment to Contributor-plus team member for initial proposal review - @shubham1206agra (External)

[melvin-bot]

Job added to Upwork: https://www.upwork.com/jobs/~022051343848904319955

[nabi-ebrahimi]

🚨 Edited by proposal-police: This proposal was edited at 2026-05-04 23:26:53 UTC.

Proposal

Please re-state the problem that we are trying to solve in this issue.

npm run storybook is not giving a good local development experience. Storybook is slow to start, prints a large number of react-docgen parsing warnings, and some stories do not render reliably because the global Storybook preview is mounting app-specific context that isolated stories do not always support.

What is the root cause of that problem?

There are two related configuration problems:

1. Storybook Docs is enabled, but the current main.ts does not explicitly disable React docgen. In Storybook v10, that means Storybook still runs react-docgen across a very large React + TypeScript codebase, which causes the repeated Failed to parse ... with react-docgen warnings and significantly slows startup.

2. The global provider tree in .storybook/preview.tsx includes SearchContextProvider. That provider is tightly coupled to app navigation and search state, so mounting it for every story adds unnecessary runtime dependencies and can break otherwise simple component stories.

A smaller maintainability issue is that the config was importing Storybook types from internal paths instead of the public framework package.

What changes do you think we should make in order to solve the problem?

We should make two targeted configuration changes:

1. Update .storybook/main.ts to use the public Storybook v10 config type and explicitly disable docgen:

import type {StorybookConfig} from '@storybook/react-webpack5';

typescript: {
    reactDocgen: false,
},

2. Simplify .storybook/preview.tsx so that only broadly safe global providers remain. In particular, remove SearchContextProvider from the global Storybook decorator tree and keep only the generic providers that are needed across stories.

This keeps Storybook lightweight, avoids unnecessary repo-wide parsing, and prevents app-specific search/navigation context from affecting unrelated stories.

What alternative solutions did you explore? (Optional)

• Keeping react-docgen enabled or switching to react-docgen-typescript: rejected because the repo is large and the startup cost and warning volume remain too high.
• Wrapping all stories in a navigation container to satisfy SearchContextProvider: rejected because it introduces app-specific navigation behavior into every story and makes Storybook less isolated and harder to maintain.
• Adding per-story workarounds for the affected stories: rejected because it spreads configuration complexity across stories instead of fixing the global setup cleanly.

Fixed Demo:

Screencast.From.2026-05-05.00-21-49.mp4

[HenriqueCosta05]

Proposal

What is the root cause of that problem?

Storybook is treated as an optional side artifact instead of a required part of the dev-facing docs delivery path.
Both the Storybook build job and the artifact download step are allowed to fail without breaking the deploy, so a broken Storybook build or publish step can be hidden. As a result, the main app deploy can succeed while the dev host still serves a missing or stale Storybook bundle, which makes Storybook appear broken even though the deployment completed.

What changes do you think we should make in order to solve the problem?

Split Storybook publication into a first-class step with explicit success or failure, separate from the main app deploy.
Remove the silent failure behavior around the Storybook build and artifact handoff so the pipeline surfaces problems immediately.
Add a post-publish check that verifies the Storybook entrypoint is actually present and reachable on the dev host.
If Storybook cannot be built or published, fail the Storybook job and alert the team instead of shipping a deployment without working docs.

[github-actions]

⚠️ @nabi-ebrahimi Thanks for your proposal. Please update it to follow the proposal template, as proposals are only reviewed if they follow that format (note the mandatory sections).

[Femimat]

Proposal

What is the problem we are trying to solve?

npm run storybook is failing for dev — Storybook does not start or crashes when trying to render app components locally.

What is the root cause of that problem?

Likely causes (investigation required; one or more apply):

• Storybook’s web bundler/config does not resolve the project’s TypeScript path aliases (@src, etc.), so imports (TSX files) fail at build time.
• Native-only modules/hooks (react-native, react-navigation hooks like useFocusEffect, Onyx, etc.) are executed in the Storybook web environment and throw runtime errors because they are not provided/mocked.
• Storybook webpack / babel config is missing React Native / Metro compatibility or necessary transforms for TSX and RN-style imports.
• A TypeScript/compile error in a recently touched file (e.g., IOURequestStepAmount.tsx) breaks Storybook’s build. We must reproduce to identify which of the above is the immediate breaker.

What changes do you think we should make in order to solve the problem?

Investigation steps (one-time):

1. Reproduce locally: run npm run storybook and capture the failing logs (terminal + browser console). Identify the first error stack (compile vs runtime).
2. If the failure is path/TS compile: update Storybook webpack to read tsconfig path aliases (copy tsconfig paths into webpack resolve.alias / use tsconfig-paths-webpack-plugin) and ensure ts-loader/babel-loader handles .tsx.
3. If the failure is native-only modules or hooks:

• Add Storybook config mocks/shims for native modules used by UI components (Onyx, react-native-onyx, react-navigation hooks, native components).
• Provide Storybook decorators that wrap stories with minimal providers required at render-time:
• A mocked Onyx provider / useOnyx shim or a simple context provider that returns safe defaults.
• A NavigationContainer wrapper or a small Navigation mock exposing useFocusEffect/useNavigation hooks as no-ops.
• Ensure Base RN components used in stories are mapped to web-safe stubs if necessary.

4. If the failure is a TypeScript/logic bug in a component (compile or runtime), fix the component to be resilient when rendered in Storybook (guard hooks, defensive checks) or ensure a mock provider supplies needed data.
5. Ensure Storybook’s preview.tsx automatically wraps all stories with the providers/mocks above and that the storybook build runs via the same babel/ts settings as the app (align preset-env/preset-react/preset-typescript).
6. Add a local run sanity check to package.json and CI job (optional): npm run storybook:build or npm run storybook -- -s public as a smoke test in CI to avoid regressions.

Minimal changes to implement first (safe, low risk):

• Add provider/decorator and lightweight mocks in .storybook/preview.<ts|tsx> so stories render without app runtime.
• Update .storybook/main.<js|ts> webpack config to honor tsconfig paths.
• Add a test build step in CI to ensure storybook starts.

Why this approach:

• Keeps app code unchanged (no production code refactors).
• Makes Storybook a faithful, isolated environment by providing required app context/mocks.
• Quick to test and low-risk to merge.

What alternative solutions did you explore? (Optional)

• Refactor components to avoid native hooks when mounted outside navigation: fragile and couples production code to Storybook; rejected.
• Run Storybook inside a native environment (emulator): heavyweight and reduces developer convenience.
• Create separate “web-only” components for Storybook: more work and increases maintenance burden.

Tests & verification

• Local: run npm run storybook, open the Storybook UI, verify it loads and the main component stories render without crashing.
• Smoke: confirm a handful of representative stories (pages and shared components like MoneyRequestAmountForm, IOURequestStepAmount) render.
• CI: add a job to run a headless Storybook build (storybook build) or start+check health endpoint to prevent regressions.

[github-actions]

⚠️ @HenriqueCosta05 Thanks for your proposal. Please update it to follow the proposal template, as proposals are only reviewed if they follow that format (note the mandatory sections).