Storybook использует отдельный процесс сборки, в котором Webpack выступает центральным инструментом компиляции и связывания модулей. Архитектура построена вокруг разделения окружений: preview (рендер компонентов) и manager (интерфейс Storybook). Оба окружения имеют собственные конфигурации Webpack, которые частично пересекаются, но решают разные задачи.
Preview-часть отвечает за выполнение компонентов, их зависимостей, стилей, ассетов и всего, что необходимо для изоляции stories. Manager-часть формирует UI панели, навигацию, тулбары и интеграции аддонов.
Внутренняя сборка Storybook фактически представляет собой два независимых Webpack-проекта.
Preview Webpack:
Manager Webpack:
Разделение снижает связанность и позволяет оптимизировать каждую сборку отдельно. Manager часто собирается быстрее и имеет более стабильную конфигурацию, в то время как preview адаптируется под проект.
Конфигурация Webpack в Storybook не статична. Она формируется
динамически через набор пресетов и функций, определяемых в
.storybook/main.js (или
.storybook/main.ts).
Основная структура:
module.exports = {
stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
addons: [
'@storybook/addon-essentials',
],
webpackFinal: async (config) => {
return config;
},
};На этапе запуска Storybook:
webpackFinalКонфигурация, генерируемая Storybook, включает несколько ключевых блоков:
Entry зависит от режима:
preview:
manager:
Output настроен как SPA-бандл, обычно в memory filesystem при dev-режиме:
Storybook расширяет resolution:
@storybook/*).ts, .tsx,
.js, .jsx, .mjsWebpack loader pipeline в Storybook является одной из самых сложных частей системы, поскольку он объединяет пользовательский код и инфраструктурный код Storybook.
Основной слой обработки:
Типичный пайплайн:
TS/JS → Babel/TS loader → Webpack AST → bundleStorybook автоматически добавляет presets:
@babel/preset-react@babel/preset-typescript@babel/preset-envCSS-цепочка зависит от проекта:
Особенность Storybook — разделение CSS между preview и manager, что исключает конфликты глобальных стилей.
Webpack 5 asset modules используются по умолчанию:
asset/resource для файловasset/inline для мелких ресурсовasset для автоматического выбораSVG может обрабатываться двумя режимами:
Storybook часто добавляет @svgr/webpack в pipeline для
поддержки иконок.
Аддоны Storybook являются не только UI расширениями, но и участниками Webpack pipeline.
Некоторые аддоны:
webpackFinalПример поведения:
MDX pipeline:
MDX → mdx-loader → Babel → Webpack bundleКлючевой точкой кастомизации выступает webpackFinal.
Конфигурация передается как объект Webpack и может быть изменена:
Пример расширения:
webpackFinal: async (config) => {
config.resolve.alias['@'] = path.resolve(__dirname, '../src');
config.module.rules.push({
test: /\.graphql$/,
use: 'graphql-tag/loader',
});
return config;
};Особенность: Storybook не пересоздает конфиг полностью, а накладывает изменения поверх базовой системы.
Webpack plugins в Storybook используются для:
Типичные плагины:
Manager и preview используют разные наборы плагинов, чтобы не перегружать runtime.
Storybook добавляет собственную систему resolution, которая может конфликтовать с проектными настройками:
Для предотвращения проблем используется:
Webpack в Storybook активно использует:
HMR особенно важен для preview, так как позволяет обновлять stories без полной перезагрузки.
Кэширование ускоряет повторные запуски, особенно при больших monorepo.
Webpack splitChunks применяется для:
Типичная структура:
Это снижает нагрузку на браузер при работе с большим количеством stories.
MDX в Storybook является отдельным слоем поверх Webpack.
Pipeline включает:
MDX позволяет описывать stories как смесь markdown и React компонентов, что требует дополнительной AST трансформации.
После сборки Webpack Storybook переходит в runtime-режим:
Manager управляет preview через postMessage API, а Webpack-бандл предоставляет исполняемую среду для stories.
На практике часто возникают следующие классы проблем:
Разные presets между проектом и Storybook приводят к ошибкам трансформации JSX или decorators.
Webpack resolution может подтянуть две версии React, что вызывает runtime ошибки hooks.
Глобальные стили могут проникать в manager через неправильные loaders.
Причины:
Несмотря на гибкость, Webpack накладывает ограничения:
Эти ограничения частично компенсируются абстракциями Storybook, но не устраняются полностью.
Storybook позволяет встраивать пользовательские правила:
При этом важно учитывать порядок применения конфигураций, так как Storybook сначала формирует базу, а затем применяет пользовательские изменения.
В monorepo структурах Webpack Storybook сталкивается с:
Для корректной работы часто требуется:
Hot Module Replacement реализован через Webpack dev server и client runtime Storybook.
Процесс обновления:
HMR работает на уровне модулей, а не всего приложения, что обеспечивает быстрый feedback loop при разработке компонентов.