Version Management

Upgrade Storybook packages to newer versions with compatibility checks and automigrations. The upgrade system handles dependency management, version conflicts, and automatically applies necessary migrations to keep your Storybook installation up-to-date and compatible.

Capabilities

Upgrade Command

Upgrades Storybook packages to the latest compatible version with automated migration support.

storybook upgrade [options]

Options:
  --package-manager <npm|pnpm|yarn1|yarn2|bun>  Force package manager for installing dependencies
  -y, --yes                            Skip prompting the user
  -f, --force                          Force the upgrade, skipping autoblockers
  -n, --dry-run                        Only check for upgrades, do not install
  -s, --skip-check                     Skip postinstall version and automigration checks
  -c, --config-dir <dir-name...>       Directory(ies) where to load Storybook configurations from

Usage Examples:

# Basic upgrade to latest version
npx storybook upgrade

# Upgrade with specific package manager
npx storybook upgrade --package-manager yarn1

# Check what would be upgraded without installing
npx storybook upgrade --dry-run

# Force upgrade, bypassing compatibility checks
npx storybook upgrade --force

# Skip prompts and use defaults
npx storybook upgrade --yes

# Upgrade and skip postinstall checks
npx storybook upgrade --skip-check

# Upgrade multiple Storybook configurations
npx storybook upgrade --config-dir .storybook --config-dir packages/*/\.storybook

Version Detection

The upgrade system detects and manages various Storybook package versions:

1. Core packages - @storybook/core-*, storybook
2. Framework packages - @storybook/react, @storybook/vue3, etc.
3. Addon packages - @storybook/addon-*
4. Builder packages - @storybook/builder-*
5. CLI packages - @storybook/cli

Autoblock System

Automated checks prevent problematic upgrades:

• Incompatible dependencies - Blocks upgrades that would break existing functionality
• Framework conflicts - Prevents version mismatches between framework packages
• Node.js version - Ensures Node.js compatibility
• Package manager issues - Detects and prevents known package manager problems

Multi-Project Support

Handle monorepos and multiple Storybook instances:

# Upgrade all Storybook configurations in a monorepo
npx storybook upgrade --config-dir packages/app/.storybook --config-dir packages/components/.storybook

# Automatically discover Storybook configurations
npx storybook upgrade  # Discovers .storybook directories automatically

Dependency Management

The upgrade process handles:

1. Version consistency - Ensures all Storybook packages use compatible versions
2. Peer dependencies - Updates peer dependencies as needed
3. Dev vs production - Correctly categorizes dependencies
4. Lock file updates - Updates package-lock.json, yarn.lock, or pnpm-lock.yaml

Upgrade Validation

Post-upgrade validation includes:

• Version consistency checks - Verifies all packages are compatible
• Configuration validation - Ensures configs are valid after upgrade
• Automatic migrations - Runs necessary codemods and fixes
• Doctor checks - Identifies potential issues

Programmatic Usage

import { upgrade } from "@storybook/cli";

/**
 * Upgrade Storybook packages programmatically
 * @param options - Upgrade configuration
 */
function upgrade(options: UpgradeOptions): Promise<void>;

interface UpgradeOptions {
  packageManager?: PackageManagerName;
  yes?: boolean;
  force?: boolean;
  dryRun?: boolean;
  skipCheck?: boolean;
  configDir?: string[];
}

/**
 * Extract Storybook version from npm output line
 * @param line - npm output line
 * @returns Package info or null
 */
function getStorybookVersion(line: string): Package | null;

/**
 * Check version consistency across Storybook packages
 * @param packages - List of package information
 * @returns Consistency check results
 */
function checkVersionConsistency(packages: Package[]): ConsistencyResult;

interface Package {
  package: string;
  version: string;
}

type PackageManagerName = "npm" | "pnpm" | "yarn1" | "yarn2" | "bun";

Programmatic Examples:

import { upgrade, getStorybookVersion } from "@storybook/cli";

// Upgrade programmatically
await upgrade({
  packageManager: "npm",
  yes: true,
  dryRun: false
});

// Parse version from npm output
const packageInfo = getStorybookVersion("@storybook/react@7.6.17");
// Returns: { package: "@storybook/react", version: "7.6.17" }

Version Compatibility

The upgrade system maintains compatibility with:

• LTS versions - Long-term support versions with extended compatibility
• Current versions - Latest stable releases
• Prerelease versions - Alpha, beta, and release candidate versions
• Framework versions - Ensures framework adapter compatibility

Upgrade Strategies

Different approaches for different scenarios:

1. Patch upgrades - Safe bug fixes and minor improvements
2. Minor upgrades - New features with backward compatibility
3. Major upgrades - Breaking changes requiring migration
4. Prerelease upgrades - Early access to upcoming features

Error Handling

Robust error handling for common upgrade issues:

• Network failures - Retry logic for package downloads
• Permission errors - Clear guidance for permission issues
• Dependency conflicts - Resolution strategies for conflicts
• Migration failures - Rollback options for failed upgrades