Storybook集成项目后部分Stories报错：Cannot access '__WEBPACK_DEFAULT_EXPORT__' before initialization

I’ve run into this exact issue before when working with Storybook and global TypeScript interfaces—let’s break down what’s happening and how to fix it.

What’s Causing This? #

This error almost always boils down to module initialization order issues or hidden circular dependencies, especially when your component/story relies on globally defined types. Storybook’s Webpack setup can sometimes resolve modules in an order where your component hasn’t fully initialized before the story tries to reference its default export.

Step-by-Step Solutions #

1. Hunt Down Circular Dependencies

First, check if there’s a circular reference between your InviteUserModal component, its dependencies, or the global type files. For example:

• Does your component import a utility that imports the global interface, which in turn imports the component?
• Use tools like madge (run npx madge --circular ./src) to auto-detect cycles, or manually trace your import chains.

To fix it:

• Extract shared types into a standalone, dependency-free file (e.g., src/types/shared.ts) that no other module imports from except the ones that need the types.
• Refactor import statements to break the cycle.

2. Explicitly Import Global Types (Don’t Rely on Auto-Imports)

If you’ve set up global types via tsconfig.json (using typeRoots or types), try explicitly importing the interface in your story file instead of relying on implicit global access. For example:

import { ComponentProps } from 'react';
import InviteUserModal from './InviteUserModal';
// Add this line to explicitly import your global interface
import { YourGlobalInterface } from '../path/to/your-global-types-file';
import type { Meta, Story } from '@storybook/react';

export default {
  title: 'modals/InviteUserModal',
  component: InviteUserModal,
} as Meta;

const Template: Story<ComponentProps<typeof InviteUserModal>> = (args) => (
  <InviteUserModal {...args} />
);

export const Modal = Template.bind({});
Modal.args = {
  isOpen: true,
};

This ensures the type is loaded before your story tries to use it, avoiding initialization race conditions.

3. Tweak Storybook’s Webpack Configuration

Sometimes Storybook’s default Webpack setup struggles with ES module resolution for TypeScript. Update your .storybook/main.js to add explicit Babel handling for TypeScript files:

module.exports = {
  stories: ['../src/**/*.stories.tsx'],
  addons: ['@storybook/addon-essentials'],
  webpackFinal: async (config) => {
    // Add TypeScript loader with CommonJS transformation
    config.module.rules.push({
      test: /\.(ts|tsx)$/,
      use: [
        {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-react', '@babel/preset-typescript'],
            plugins: ['@babel/plugin-transform-modules-commonjs'],
          },
        },
      ],
    });
    return config;
  },
};

This forces consistent module resolution and can fix the "before initialization" error.

4. Delay Component Reference in Stories

If all else fails, try wrapping your component reference to delay its initialization until the story is ready:

import { ComponentProps } from 'react';
import type { Meta, Story } from '@storybook/react';

// Declare component type first, then import dynamically
let InviteUserModal: React.ComponentType<ComponentProps<any>>;
import('./InviteUserModal').then(mod => {
  InviteUserModal = mod.default;
});

export default {
  title: 'modals/InviteUserModal',
  component: () => InviteUserModal, // Use a function to delay reference
} as Meta;

const Template: Story<ComponentProps<typeof InviteUserModal>> = (args) => (
  <InviteUserModal {...args} />
);

export const Modal = Template.bind({});
Modal.args = {
  isOpen: true,
};

Note: You may need to adjust TypeScript types slightly to avoid type errors here.

5. Update Storybook and Dependencies

Old versions of Storybook have known bugs with module initialization. Run this to upgrade to the latest stable version:

npx storybook@latest upgrade

Also ensure your typescript, @babel/core, and @storybook/react versions are compatible (check the Storybook docs for version matrixes).

Final Notes #

Start with checking for circular dependencies—this is the most common culprit. If that doesn’t work, move to explicit type imports and Webpack tweaks. Most of the time, one of these steps will resolve the issue.

内容的提问来源于stack exchange，提问作者Jan Bo