Project Diagnostics

Check Storybook installations for known problems and provide suggestions or fixes. The diagnostics system analyzes your Storybook setup to identify configuration issues, dependency problems, and compatibility concerns.

Capabilities

Doctor Command

Comprehensive health check for Storybook installations with detailed problem reporting and fix suggestions.

storybook doctor [options]

Options:
  --package-manager <npm|pnpm|yarn1|yarn2|bun>  Force package manager
  -c, --config-dir <dir-name>          Directory of Storybook configuration

Usage Examples:

# Run full diagnostic check
npx storybook doctor

# Run with specific package manager
npx storybook doctor --package-manager yarn1

# Check custom config directory
npx storybook doctor --config-dir .custom-storybook

# Run doctor with verbose output
npx storybook doctor --loglevel debug

Info Command

Display system and environment information for debugging and support.

storybook info

Usage Examples:

# Display environment information
npx storybook info

# Show detailed system info
npx storybook info --loglevel debug

Diagnostic Categories

The doctor command checks multiple areas:

Configuration Issues

• Invalid main.js/ts - Syntax errors and configuration problems
• Missing required fields - Essential configuration missing
• Deprecated options - Usage of deprecated configuration options
• Framework compatibility - Framework and addon compatibility issues

Dependency Problems

• Version mismatches - Incompatible package versions
• Missing dependencies - Required packages not installed
• Duplicate dependencies - Multiple versions of same package
• Peer dependency issues - Unmet peer dependency requirements

Environment Issues

• Node.js version - Incompatible Node.js versions
• Package manager - Package manager configuration problems
• File system - Permission and access issues
• Network connectivity - CDN and registry access problems

Framework-Specific Checks

• React issues - React-specific configuration problems
• Vue issues - Vue-specific setup problems
• Angular issues - Angular CLI integration issues
• TypeScript issues - TypeScript configuration problems

System Information

The info command displays comprehensive system information:

System Details

• Operating System - OS type, version, and architecture
• CPU Information - Processor details and architecture
• Shell Environment - Active shell and environment variables

Runtime Information

• Node.js - Version, installation path, and configuration
• Package Managers - Available package managers and versions
• Browser Information - Installed browsers and versions

Storybook Packages

• Core packages - Versions of all @storybook/* packages
• Addons - Installed addon packages and versions
• Related packages - Chromatic, Storybook-related tools

Global Packages

• Global installations - Globally installed Storybook packages
• CLI tools - Related CLI tools and versions

Multi-Project Diagnostics

Handle monorepos and multiple Storybook configurations:

# Automatically discover and check all Storybook projects
npx storybook doctor

# Check specific config directories
npx storybook doctor --config-dir packages/app/.storybook

Diagnostic Results

Doctor checks return structured results:

interface DiagnosticResult {
  type: DiagnosticType;
  status: DiagnosticStatus;
  message: string;
  details?: string;
  suggestion?: string;
  fixable?: boolean;
}

enum DiagnosticType {
  CONFIGURATION = "configuration",
  DEPENDENCY = "dependency", 
  ENVIRONMENT = "environment",
  FRAMEWORK = "framework"
}

enum DiagnosticStatus {
  PASS = "pass",
  WARN = "warn", 
  ERROR = "error",
  INFO = "info"
}

Problem Detection

Common issues detected by doctor:

Critical Issues (Errors)

• Missing main configuration - No main.js/ts file found
• Invalid JSON/JS syntax - Syntax errors in configuration files
• Missing framework - No framework specified or installed
• Version conflicts - Incompatible package versions

Warnings

• Deprecated configurations - Usage of deprecated options
• Suboptimal settings - Non-recommended but functional settings
• Missing recommended addons - Suggested addons not installed
• Performance issues - Configuration that may impact performance

Information

• Version recommendations - Newer versions available
• Feature suggestions - New features that might be useful
• Best practices - Recommendations for better configuration

Fix Suggestions

For each identified issue, doctor provides:

1. Problem description - Clear explanation of the issue
2. Impact assessment - How the issue affects your Storybook
3. Fix suggestions - Step-by-step resolution instructions
4. Automigration availability - Whether an automigration can fix it
5. Related documentation - Links to relevant documentation

Integration with Automigrate

Doctor seamlessly integrates with the automigration system:

# Run doctor and then apply suggested automigrations
npx storybook doctor
npx storybook automigrate

# Skip doctor when running automigrations
npx storybook automigrate --skip-doctor

Programmatic Usage

import { doctor, runMultiProjectDoctor } from "@storybook/cli";

/**
 * Run doctor checks programmatically
 * @param options - Doctor configuration
 */
function doctor(options: DoctorOptions): Promise<void>;

/**
 * Run doctor across multiple projects
 * @param projects - List of project configurations
 * @param options - Doctor options
 */
function runMultiProjectDoctor(
  projects: CollectProjectsSuccessResult[],
  options: DoctorOptions
): Promise<ProjectDoctorResults[]>;

interface DoctorOptions {
  packageManager?: PackageManagerName;
  configDir?: string;
}

interface ProjectDoctorResults {
  configDir: string;
  results: DiagnosticResult[];
  summary: DiagnosticSummary;
}

interface DiagnosticSummary {
  errors: number;
  warnings: number;
  infos: number;
  total: number;
}

Programmatic Examples:

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

// Run doctor programmatically
await doctor({
  packageManager: "npm",
  configDir: ".storybook"
});

Output Formats

Doctor provides multiple output formats:

Console Output (default)

• Colored output - Color-coded results for easy scanning
• Structured sections - Organized by diagnostic categories
• Progress indicators - Shows check progress
• Summary statistics - Count of errors, warnings, and info

JSON Output

# Generate JSON output for programmatic use
npx storybook doctor --json > doctor-results.json

Detailed Reporting

# Get detailed diagnostic information
npx storybook doctor --verbose

Error Recovery

Doctor helps with error recovery:

• Safe mode detection - Identifies when Storybook is in degraded state
• Recovery suggestions - Step-by-step recovery instructions
• Backup recommendations - When to backup before making changes
• Rollback guidance - How to undo problematic changes