How to Cleanly Swap Between React Native Storybook 10 and Your App

Back in 2023, I wrote a post on the same topic, titled How to swap between React Native Storybook and your app.

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, 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 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 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.

I have also set up a blank TypeScript example app here 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.

.rnstorybook/
src/index.tsx
app.tsx
metro.config.js

Make sure you’ve already added the withStorybook function to your Metro config like this:‍

// 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:

{
  "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.

// 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 ? <StorybookUI/> : <AppRoot />;
}

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.

// 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.

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.

// app/_layout.tsx

export default function RootLayout() {
  return (
    <Stack screenOptions={{ headerShown: false }}>
      <Stack.Screen name="index" />

      <Stack.Protected
        guard={process.env.EXPO_PUBLIC_STORYBOOK_ENABLED === "true"}
      >
        <Stack.Screen name="storybook" />
      </Stack.Protected>
    </Stack>
  );
}

Community CLI

If you are using the Community CLI or 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.

Let's assume you have a project like this

.rnstorybook/
src/index.tsx
app.tsx
metro.config.js

Make sure you’ve already added the withStorybook function to your Metro config like this:

// 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:

npm install babel-plugin-transform-inline-environment-variables

Now, add the plugin to your babel.config.js:‍

//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:

{
  "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.

// App.tsx
import StorybookUI from './.rnstorybook';
import { AppRoot } from './src';

const isStorybook = process.env.STORYBOOK_ENABLED === 'true';

export default function App() {
  return isStorybook ? <StorybookUI/> : <AppRoot />;
}

‍

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:

// 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, you'll find an example that nicely illustrates how you can use resolvers to mock out a module.

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.

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.

  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.

import StorybookUI from './.rnstorybook';
export default function App() {
  return isStorybook ? <StorybookUI/> : <AppRoot />;
}

‍

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.

‍