--- title: "How to Cleanly Swap Between React Native Storybook 10 and Your App" description: "Set up React Native Storybook 10 with Expo or the Community CLI. Learn configuration steps, updated tools and a simple workflow for toggling Storybook." url: https://www.callstack.com/blog/how-to-cleanly-swap-between-react-native-storybook-10-and-your-app updated: 2026-10-25T20:07:25.389Z --- # How to Cleanly Swap Between React Native Storybook 10 and Your App Set up React Native Storybook 10 with Expo or the Community CLI. Learn configuration steps, updated tools and a simple workflow for toggling Storybook. _By Daniel Williams, Senior Software Engineer @ Callstack · Published 2025-12-12 · Category: React Native_ Back in 2023, I wrote a post on the same topic, titled [How to swap between React Native Storybook and your app](https://dev.to/dannyhw/how-to-swap-between-react-native-storybook-and-your-app-p3o). A lot has changed since then. I was honestly surprised with how many people actually found that tutorial useful. However,  the original post has now become quite outdated, which is why I wanted to revisit this topic. In this updated version, I'd like to show you how much easier the whole process  is today and how to make sure that nothing leaks into your production bundle. ## What's changed? A number of updates have been introduced that make the process simpler today. Let's go through them. ### Built-in support for environment variables in Expo At the time of the original post, there wasn't a built-in solution for environment [variables in Expo](https://docs.expo.dev/guides/environment-variables/), which is why we made use of Expo Constants. This worked as well, but required a few extra steps. ### The withStorybook Metro helper function In newer versions of React Native Storybook, we now include a Metro helper that applies some [Metro configuration](https://storybookjs.github.io/react-native/docs/intro/configuration/metro-configuration/) and handles generating your story imports. This also made it possible for us to introduce improvements to how we enable/disable Storybook. ### Metro improvements We've also gained some newer [configuration options in Metro](https://docs.expo.dev/versions/latest/config/metro/#custom-resolving) such as `resolver.resolveRequest` that allow you to override some resolver functionality with your own logic. For example, for Storybook files, we make sure that `enablePackageExports` is enabled. ## Let's get into it I'll split this into Expo and community CLI guides, so scroll down if you aren't using Expo. ## The Expo guide I'm going to assume you already have a project set up to keep things simple. If you want to see how to get started  with Expo Router,  [check out my article on the Expo blog](https://expo.dev/blog/storybook-and-expo). I have also set up a blank TypeScript [example app here](https://github.com/dannyhw/how-to-swap-storybook-example) that only has Storybook setup. In the pull requests for this repository, I also made the same changes outlined below. Let's assume you have a project like this with the basic setup for Storybook already done. ```bash .rnstorybook/ src/index.tsx app.tsx metro.config.js ``` Make sure you’ve already added the `withStorybook `function to your Metro config like this:`‍` ```javascript // metro.config.js const { getDefaultConfig } = require("expo/metro-config"); const { withStorybook, } = require("@storybook/react-native/metro/withStorybook"); /** @type {import('expo/metro-config').MetroConfig} */ const config = getDefaultConfig(__dirname); module.exports = withStorybook(config); ``` Now, let's take a look at a simple way, in which you can add storybook to your app and still be able to swap back to your application whenever you need to. ### Use an environment variable First, let's add a Storybook script to our `package.json`: ```json { "scripts": { "storybook": "EXPO_PUBLIC_STORYBOOK_ENABLED=true expo start", } } ``` This is just the start command, but with the `EXPO_PUBLIC_STORYBOOK_ENABLED` environment variable set to true. > _Expo will inject environment variables into process.env like you might be used to from server or web frameworks._ Now let's go to our `App.tsx` and add some logic to show Storybook when our variable is set to `true`. ```typescript // App.tsx import StorybookUI from './.rnstorybook'; import { AppRoot } from './src'; const isStorybook = process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === 'true'; export default function App() { return isStorybook ? : ; } ``` Now, whenever you run `npm run storybook` you see Storybook, and whenever you run `npm run start`, you see your app. ### But my production bundle! You might notice that we're importing Storybook even when not using it. This will cause Metro to include all the dependencies in the bundle. This is where we bring in the new Metro options. Update your Metro config to pass some options to withStorybook. ```javascript // metro.config.js module.exports = withStorybook(config, { enabled: process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === "true", // <- }); ``` The `enabled` option, when set to false in version 10, will actually strip Storybook out of your bundle. I will explain a bit more about how that works at the end, in case you are interested. **That's it!** Nothing else is needed, and from here on out, you can expand on this idea and come up with more developer-friendly ways to hide/show Storybook. One example is to create a dev menu option and use it to toggle Storybook in combination with the environment variable. Your browser does not support the video tag. ### Expo Router With Expo Router, I recommend putting Storybook in its own route and using a protected route to disable it when Storybook is not enabled. ```typescript // app/_layout.tsx export default function RootLayout() { return ( ); } ``` ## Community CLI If you are using the [Community CLI](https://github.com/react-native-community/template) or [Rock](https://www.callstack.com/open-source/rock), you can follow this guide. I'm going to assume you already have a project setup to keep things simple. You can find an [example project here](https://github.com/dannyhw/react-native-storybook-starter). Let's assume you have a project like this ```bash .rnstorybook/ src/index.tsx app.tsx metro.config.js ``` Make sure you’ve already added the `withStorybook` function to your Metro config like this: ```javascript // metro.config.js const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config'); const { withStorybook, } = require("@storybook/react-native/metro/withStorybook"); const config = {}; const finalConfig = mergeConfig(getDefaultConfig(__dirname), config); module.exports = withStorybook(finalConfig); ``` Now, let's look at a simple way, in which you can add Storybook to your app and still be able to swap back to your application when you need to. ### Use an environment variable By using the Babel plugin `babel-plugin-transform-inline-environment-variables` we can get environment variables on `process.env` and use that to make things easier.First, install the package: ```bash npm install babel-plugin-transform-inline-environment-variables ``` Now, add the plugin to your `babel.config.js`:`‍` ```javascript //babel.config.js module.exports = { presets: ['module:@react-native/babel-preset'], plugins: [ 'transform-inline-environment-variables', // <-- ], }; ``` Let's add a Storybook script to our `package.json`: ```json { "scripts": { "storybook": "STORYBOOK_ENABLED=true react-native start", } } ``` This is just the start command but with the `STORYBOOK_ENABLED` environment variable set to true. Now, let's go to our app and add a simple bit of logic for toggling Storybook. ```typescript // App.tsx import StorybookUI from './.rnstorybook'; import { AppRoot } from './src'; const isStorybook = process.env.STORYBOOK_ENABLED === 'true'; export default function App() { return isStorybook ? : ; } ``` Now, whenever you use `npm run storybook` you see Storybook and whenever you use `npm run start`, you see your app. ### But my production bundle! You might notice that we're importing Storybook even when not using it. This will cause Metro to include all the dependencies in the bundle. However, this is where we bring in the new Metro options. Update your Metro config to pass some `enabled` option to `withStorybook` helper: ```javascript // metro.config.js module.exports = withStorybook(finalConfig, { enabled: process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === "true", // <- }); ``` The `enabled` option, when set to false in version 10 and higher, will actually strip Storybook out of your bundle. **That's it!** Nothing else is needed. From here on out you can expand on this idea and come up with more developer friendly ways to hide/show Storybook. For example, you can create a dev menu option and use it to toggle Storybook in combination with the environment variable. ## How does this work under the hood? The `withStorybook` wrapper makes use of custom resolvers like I've mentioned earlier in this post. First, let me expand a bit on what I mean by that. ### Mocking with Metro If you look at the [Expo docs about Metro](https://docs.expo.dev/versions/latest/config/metro/#mocking-modules), you'll find an example that nicely illustrates how you can use resolvers to mock out a module. ```javascript const { getDefaultConfig } = require('expo/metro-config'); /** @type {import('expo/metro-config').MetroConfig} */ const config = getDefaultConfig(__dirname); config.resolver.resolveRequest = (context, moduleName, platform) => { if (platform === 'web' && moduleName === 'lodash') { return { type: 'empty', }; } // Ensure you call the default resolver. return context.resolveRequest(context, moduleName, platform); }; module.exports = config; ``` By returning `type: 'empty'`, Metro will essentially just ignore that entire codepath and you won't find it in your bundle anymore. However, this isn't limited to just `'empty'`, you can also swap out the file that's used. ```javascript return { filePath: 'path-to-file-here', type: 'sourceFile', }; ``` ### The implementation in Storybook In Storybook, we combine both the `empty` and `sourceFile` mocking to make sure we correctly remove Storybook fully when it’s disabled. We will return `empty` for anything in your `.rnstorybook` folder and replace `.rnstorybook/index.tsx` with a file that imports nothing and exports a component warning you that Storybook is disabled. ```typescript if (!enabled) { return { ...config, resolver: { ...config.resolver, resolveRequest: (context: any, moduleName: string, platform: string | null) => { const resolveFunction: ResolveRequestFunction = config?.resolver?.resolveRequest ? config.resolver.resolveRequest : context.resolveRequest; const resolved = resolveFunction(context, moduleName, platform); if (resolved.filePath?.includes?.(`${configPath}/index.tsx`)) { return { filePath: path.resolve(__dirname, '../stub.js'), type: 'sourceFile', }; } if (resolved.filePath?.includes?.(configPath)) { return { type: 'empty' }; } return resolved; }, }, }; } ``` The reason why we specifically stub out the `index` file is that if you have this code and `StorybookUI` isn't a component, then it's going to crash. ```typescript import StorybookUI from './.rnstorybook'; export default function App() { return isStorybook ? : ; } ``` Replacing  `.rnstorybook/index.tsx` with a placeholder component instead of treating it as an empty file makes sure that the app won’t crash. It also ensures that the Storybook code is still removed from the bundle since the placeholder component has no dependencies. ## In conclusion The process for swapping between Storybook and your app is much simpler than it used to be. With environment variables, Metro’s custom resolver options, and the new _withStorybook_ helper, you can keep Storybook fully isolated from your production bundle while still making it easy to enable in development. Use this guide as a base and tailor the workflow to whatever suits your team best.