Builder vs Framework Precedence in Storybook 7 – Which Setting Wins?

Short answer

In Storybook 7, the framework key wins. A framework preset such as @storybook/react-vite or @storybook/react-webpack5 bundles both the renderer and the builder, so the builder is implied by the framework package you name. The top-level builder key is a deprecated legacy option; it is only honored in setups where no framework preset supplies a builder. When both are present and conflict, the framework's builder prevails.

Why users see inconsistent behavior

The confusion usually comes from mixing a builder-specific framework package with a conflicting explicit key:

// .storybook/main.js
export default {
  framework: '@storybook/react-vite', // hard-codes Vite
  builder: 'webpack5',                // deprecated, effectively ignored here
};

Because @storybook/react-vite wires Vite into its own preset, builder: 'webpack5' cannot redirect it — the key appears to be silently ignored. Conversely, in older or zero-config setups without a builder-bearing framework preset, the explicit builder key is the only source and does take effect. That split explains the contradictory reports.

Caveat: exact fallback handling of a stray builder key varied across 7.x minor releases, and the key is removed entirely in Storybook 8. Treat any observed "explicit builder wins" behavior as version-specific, not contractual.

Custom frameworks

For a custom framework, the builder must come from the preset itself — the preset exports or references its builder via its options. Pointing framework at a custom preset that bundles no builder and expecting the top-level builder key to fill the gap is not a supported path in v7. If your custom preset needs Vite, wrap or extend an official Vite-based preset (e.g., re-export from @storybook/react-vite with your additions) rather than relying on the deprecated key.

Do add-ons influence selection?

No. Add-ons like @storybook/addon-essentials are largely builder-agnostic and do not participate in builder selection. Some add-ons ship builder-specific presets (for example, ones that alias webpack internals); those only fail or warn when the active builder mismatches — they never change which builder is chosen.

Recommended fix

1. Delete the top-level builder key from main.js/main.ts.
2. Choose the framework package matching the builder you want: @storybook/<renderer>-vite or @storybook/<renderer>-webpack5.
3. Verify what actually loads: run npx storybook info, or start with DEBUG=storybook:* npx storybook dev and check the startup banner and debug output for the builder name.
4. Confirm your installed version first (npm ls @storybook/core-server) before assuming any precedence behavior, and inspect the framework package's preset exports if results surprise you.

This also removes a migration hazard, since the builder key does not exist in Storybook 8.