0
# Project Initialization
1

2
Initialize Storybook in existing projects with automatic framework detection and configuration. The init command analyzes your project structure, detects the framework in use, and sets up appropriate Storybook configurations and dependencies.
3

4
## Capabilities
5

6
### Initialize Command
7

8
Sets up Storybook in an existing project with framework-specific configuration.
9

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

13
Options:
14
  -f, --force                           Force add Storybook
15
  -s, --skip-install                    Skip installing deps
16
  --package-manager <npm|pnpm|yarn1|yarn2>  Force package manager for installing deps
17
  --use-pnp                            Enable PnP mode for Yarn 2+
18
  -p, --parser <babel|babylon|flow|ts|tsx>  jscodeshift parser
19
  -t, --type <type>                    Add Storybook for a specific project type
20
  -y, --yes                            Answer yes to all prompts
21
  -b, --builder <webpack5|vite>        Builder library
22
  -l, --linkable                       Prepare installation for link (contributor helper)
23
  --dev                               Launch the development server after completing initialization (default: true)
24
  --no-dev                            Complete the initialization without launching the development server
25
```
26

27
**Usage Examples:**
28

29
```bash
30
# Basic initialization with automatic detection
31
npx storybook@latest init
32

33
# Force initialization even if Storybook already exists
34
npx storybook@latest init --force
35

36
# Initialize without installing dependencies
37
npx storybook@latest init --skip-install
38

39
# Initialize with specific package manager
40
npx storybook@latest init --package-manager yarn1
41

42
# Initialize for specific project type
43
npx storybook@latest init --type react
44

45
# Initialize with Vite builder
46
npx storybook@latest init --builder vite
47

48
# Initialize without starting dev server
49
npx storybook@latest init --no-dev
50

51
# Skip all prompts (accept defaults)
52
npx storybook@latest init --yes
53
```
54

55
### Framework Detection
56

57
The init command automatically detects your project's framework and configures Storybook accordingly. Supported frameworks include:
58

59
- **React**: Create React App, Next.js, custom React setups
60
- **Vue**: Vue CLI, Nuxt.js, custom Vue setups  
61
- **Angular**: Angular CLI projects
62
- **Svelte**: SvelteKit and custom Svelte projects
63
- **Web Components**: Lit, Stencil, and other web component frameworks
64
- **HTML**: Plain HTML/CSS/JS projects
65
- **React Native**: React Native projects
66

67
### Configuration Generation
68

69
During initialization, Storybook creates:
70

71
1. **`.storybook/` directory** with configuration files:
72
   - `main.js/ts` - Main Storybook configuration
73
   - `preview.js/ts` - Global decorators and parameters
74
   
75
2. **Story files** - Example stories for detected components
76

77
3. **Package.json scripts** - Storybook build and dev scripts
78

79
4. **Dependencies** - Framework-specific Storybook packages
80

81
### Builder Selection
82

83
Choose between different build tools:
84

85
- **Webpack 5** (default): Mature, well-tested build system
86
- **Vite**: Faster build times, modern ESM-based bundling
87

88
```bash
89
# Initialize with Vite builder
90
npx storybook@latest init --builder vite
91
```
92

93
### Development Server Control
94

95
Control whether the development server starts after initialization:
96

97
```bash
98
# Start dev server after init (default)
99
npx storybook@latest init --dev
100

101
# Don't start dev server after init
102
npx storybook@latest init --no-dev
103
```
104

105
### Package Manager Integration
106

107
Storybook integrates with all major package managers:
108

109
```bash
110
# Use specific package manager
111
npx storybook@latest init --package-manager npm
112
npx storybook@latest init --package-manager yarn1  
113
npx storybook@latest init --package-manager yarn2
114
npx storybook@latest init --package-manager pnpm
115

116
# Enable Yarn PnP mode
117
npx storybook@latest init --package-manager yarn2 --use-pnp
118
```
119

120
### Programmatic Usage
121

122
For programmatic initialization, use the `create-storybook` package which powers the CLI init command:
123

124
```typescript { .api }
125
import { initiate } from "create-storybook";
126

127
/**
128
 * Initialize Storybook in a project programmatically
129
 * @param options - Configuration options for initialization
130
 * @returns Promise that resolves when initialization is complete
131
 */
132
function initiate(options: CommandOptions): Promise<void>;
133

134
/**
135
 * Lower-level initialization function that returns setup information
136
 * @param options - Configuration options for initialization
137
 * @returns Promise with initialization results and next steps
138
 */
139
function doInitiate(options: CommandOptions): Promise<
140
  | {
141
      shouldRunDev: true;
142
      shouldOnboard: boolean;
143
      projectType: ProjectType;
144
      packageManager: JsPackageManager;
145
      storybookCommand: string;
146
    }
147
  | { shouldRunDev: false }
148
>;
149
```
150

151
**Usage Examples:**
152

153
```typescript
154
import { initiate } from "create-storybook";
155

156
// Basic programmatic initialization
157
await initiate({
158
  packageManager: "npm",
159
  skipInstall: false,
160
  yes: true,
161
  dev: false,
162
  features: ["docs", "test"]
163
});
164

165
// Initialize with specific builder
166
await initiate({
167
  packageManager: "yarn1",
168
  builder: "vite",
169
  type: ProjectType.REACT,
170
  yes: true,
171
  dev: false,
172
  features: ["docs"]
173
});
174

175
// Initialize and get setup information
176
import { doInitiate } from "create-storybook";
177

178
const result = await doInitiate({
179
  packageManager: "pnpm",
180
  yes: true,
181
  dev: true,
182
  features: ["docs", "test", "onboarding"]
183
});
184

185
if (result.shouldRunDev) {
186
  console.log(`Run: ${result.storybookCommand}`);
187
  console.log(`Project type: ${result.projectType}`);
188
}
189
```
190

191
## Types
192

193
```typescript { .api }
194
interface CommandOptions {
195
  packageManager: PackageManagerName;
196
  usePnp?: boolean;
197
  features: GeneratorFeature[];
198
  type?: ProjectType;
199
  force?: boolean;
200
  html?: boolean;
201
  skipInstall?: boolean;
202
  parser?: string;
203
  yes?: boolean;
204
  builder?: Builder;
205
  linkable?: boolean;
206
  disableTelemetry?: boolean;
207
  enableCrashReports?: boolean;
208
  debug?: boolean;
209
  dev?: boolean;
210
}
211

212
type GeneratorFeature = "docs" | "test" | "onboarding";
213

214
type Builder = CoreBuilder | string;
215

216
enum CoreBuilder {
217
  Webpack5 = "webpack5",
218
  Vite = "vite"
219
}
220

221
enum ProjectType {
222
  UNDETECTED = "UNDETECTED",
223
  UNSUPPORTED = "UNSUPPORTED", 
224
  REACT = "REACT",
225
  REACT_SCRIPTS = "REACT_SCRIPTS",
226
  REACT_NATIVE = "REACT_NATIVE",
227
  REACT_NATIVE_WEB = "REACT_NATIVE_WEB",
228
  REACT_NATIVE_AND_RNW = "REACT_NATIVE_AND_RNW",
229
  REACT_PROJECT = "REACT_PROJECT",
230
  WEBPACK_REACT = "WEBPACK_REACT",
231
  NEXTJS = "NEXTJS",
232
  VUE3 = "VUE3",
233
  NUXT = "NUXT",
234
  ANGULAR = "ANGULAR",
235
  EMBER = "EMBER",
236
  WEB_COMPONENTS = "WEB_COMPONENTS",
237
  HTML = "HTML",
238
  QWIK = "QWIK",
239
  PREACT = "PREACT",
240
  SVELTE = "SVELTE",
241
  SVELTEKIT = "SVELTEKIT",
242
  SERVER = "SERVER",
243
  NX = "NX",
244
  SOLID = "SOLID"
245
}
246

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

249
type JsPackageManager = {
250
  name: PackageManagerName;
251
  version?: string;
252
  exec: string;
253
  installArgs: string[];
254
  uninstallArgs: string[];
255
  runScript: (script: string) => string;
256
};
257
```