0
# Project Diagnostics
1

2
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.
3

4
## Capabilities
5

6
### Doctor Command
7

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

10
```bash { .api }
11
storybook doctor [options]
12

13
Options:
14
  --package-manager <npm|pnpm|yarn1|yarn2|bun>  Force package manager
15
  -c, --config-dir <dir-name>          Directory of Storybook configuration
16
```
17

18
**Usage Examples:**
19

20
```bash
21
# Run full diagnostic check
22
npx storybook doctor
23

24
# Run with specific package manager
25
npx storybook doctor --package-manager yarn1
26

27
# Check custom config directory
28
npx storybook doctor --config-dir .custom-storybook
29

30
# Run doctor with verbose output
31
npx storybook doctor --loglevel debug
32
```
33

34
### Info Command
35

36
Display system and environment information for debugging and support.
37

38
```bash { .api }
39
storybook info
40
```
41

42
**Usage Examples:**
43

44
```bash
45
# Display environment information
46
npx storybook info
47

48
# Show detailed system info
49
npx storybook info --loglevel debug
50
```
51

52
### Diagnostic Categories
53

54
The doctor command checks multiple areas:
55

56
#### Configuration Issues
57
- **Invalid main.js/ts** - Syntax errors and configuration problems
58
- **Missing required fields** - Essential configuration missing
59
- **Deprecated options** - Usage of deprecated configuration options
60
- **Framework compatibility** - Framework and addon compatibility issues
61

62
#### Dependency Problems
63
- **Version mismatches** - Incompatible package versions
64
- **Missing dependencies** - Required packages not installed
65
- **Duplicate dependencies** - Multiple versions of same package
66
- **Peer dependency issues** - Unmet peer dependency requirements
67

68
#### Environment Issues
69
- **Node.js version** - Incompatible Node.js versions
70
- **Package manager** - Package manager configuration problems
71
- **File system** - Permission and access issues
72
- **Network connectivity** - CDN and registry access problems
73

74
#### Framework-Specific Checks
75
- **React issues** - React-specific configuration problems
76
- **Vue issues** - Vue-specific setup problems  
77
- **Angular issues** - Angular CLI integration issues
78
- **TypeScript issues** - TypeScript configuration problems
79

80
### System Information
81

82
The info command displays comprehensive system information:
83

84
#### System Details
85
- **Operating System** - OS type, version, and architecture
86
- **CPU Information** - Processor details and architecture
87
- **Shell Environment** - Active shell and environment variables
88

89
#### Runtime Information  
90
- **Node.js** - Version, installation path, and configuration
91
- **Package Managers** - Available package managers and versions
92
- **Browser Information** - Installed browsers and versions
93

94
#### Storybook Packages
95
- **Core packages** - Versions of all @storybook/* packages
96
- **Addons** - Installed addon packages and versions
97
- **Related packages** - Chromatic, Storybook-related tools
98

99
#### Global Packages
100
- **Global installations** - Globally installed Storybook packages
101
- **CLI tools** - Related CLI tools and versions
102

103
### Multi-Project Diagnostics
104

105
Handle monorepos and multiple Storybook configurations:
106

107
```bash
108
# Automatically discover and check all Storybook projects
109
npx storybook doctor
110

111
# Check specific config directories
112
npx storybook doctor --config-dir packages/app/.storybook
113
```
114

115
### Diagnostic Results
116

117
Doctor checks return structured results:
118

119
```typescript { .api }
120
interface DiagnosticResult {
121
  type: DiagnosticType;
122
  status: DiagnosticStatus;
123
  message: string;
124
  details?: string;
125
  suggestion?: string;
126
  fixable?: boolean;
127
}
128

129
enum DiagnosticType {
130
  CONFIGURATION = "configuration",
131
  DEPENDENCY = "dependency", 
132
  ENVIRONMENT = "environment",
133
  FRAMEWORK = "framework"
134
}
135

136
enum DiagnosticStatus {
137
  PASS = "pass",
138
  WARN = "warn", 
139
  ERROR = "error",
140
  INFO = "info"
141
}
142
```
143

144
### Problem Detection
145

146
Common issues detected by doctor:
147

148
#### Critical Issues (Errors)
149
- **Missing main configuration** - No main.js/ts file found
150
- **Invalid JSON/JS syntax** - Syntax errors in configuration files
151
- **Missing framework** - No framework specified or installed
152
- **Version conflicts** - Incompatible package versions
153

154
#### Warnings
155
- **Deprecated configurations** - Usage of deprecated options
156
- **Suboptimal settings** - Non-recommended but functional settings
157
- **Missing recommended addons** - Suggested addons not installed
158
- **Performance issues** - Configuration that may impact performance
159

160
#### Information
161
- **Version recommendations** - Newer versions available
162
- **Feature suggestions** - New features that might be useful
163
- **Best practices** - Recommendations for better configuration
164

165
### Fix Suggestions
166

167
For each identified issue, doctor provides:
168

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

175
### Integration with Automigrate
176

177
Doctor seamlessly integrates with the automigration system:
178

179
```bash
180
# Run doctor and then apply suggested automigrations
181
npx storybook doctor
182
npx storybook automigrate
183

184
# Skip doctor when running automigrations
185
npx storybook automigrate --skip-doctor
186
```
187

188
### Programmatic Usage
189

190
```typescript { .api }
191
import { doctor, runMultiProjectDoctor } from "@storybook/cli";
192

193
/**
194
 * Run doctor checks programmatically
195
 * @param options - Doctor configuration
196
 */
197
function doctor(options: DoctorOptions): Promise<void>;
198

199
/**
200
 * Run doctor across multiple projects
201
 * @param projects - List of project configurations
202
 * @param options - Doctor options
203
 */
204
function runMultiProjectDoctor(
205
  projects: CollectProjectsSuccessResult[],
206
  options: DoctorOptions
207
): Promise<ProjectDoctorResults[]>;
208

209
interface DoctorOptions {
210
  packageManager?: PackageManagerName;
211
  configDir?: string;
212
}
213

214
interface ProjectDoctorResults {
215
  configDir: string;
216
  results: DiagnosticResult[];
217
  summary: DiagnosticSummary;
218
}
219

220
interface DiagnosticSummary {
221
  errors: number;
222
  warnings: number;
223
  infos: number;
224
  total: number;
225
}
226
```
227

228
**Programmatic Examples:**
229

230
```typescript
231
import { doctor } from "@storybook/cli";
232

233
// Run doctor programmatically
234
await doctor({
235
  packageManager: "npm",
236
  configDir: ".storybook"
237
});
238
```
239

240
### Output Formats
241

242
Doctor provides multiple output formats:
243

244
#### Console Output (default)
245
- **Colored output** - Color-coded results for easy scanning
246
- **Structured sections** - Organized by diagnostic categories
247
- **Progress indicators** - Shows check progress
248
- **Summary statistics** - Count of errors, warnings, and info
249

250
#### JSON Output
251
```bash
252
# Generate JSON output for programmatic use
253
npx storybook doctor --json > doctor-results.json
254
```
255

256
#### Detailed Reporting
257
```bash
258
# Get detailed diagnostic information
259
npx storybook doctor --verbose
260
```
261

262
### Error Recovery
263

264
Doctor helps with error recovery:
265

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