0
# Development Tools
1

2
Create sandbox environments, link repositories, and manage development workflows. These tools help developers experiment with Storybook configurations, test reproductions, and contribute to the Storybook ecosystem.
3

4
## Capabilities
5

6
### Sandbox Command
7

8
Create sandbox environments from predefined templates for testing and experimentation.
9

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

13
Parameters:
14
  filterValue                          Optional filter to narrow template selection
15

16
Options:
17
  -o, --output <outDir>                Define an output directory
18
  --no-init                           Whether to download a template without an initialized Storybook (default: false)
19
```
20

21
**Alias:** `repro` (for backward compatibility)
22

23
**Usage Examples:**
24

25
```bash
26
# Create sandbox with interactive template selection
27
npx storybook sandbox
28

29
# Filter templates by name
30
npx storybook sandbox react
31

32
# Create sandbox in specific directory
33
npx storybook sandbox react --output my-react-sandbox
34

35
# Download template without Storybook initialization
36
npx storybook sandbox vue --no-init
37

38
# Using the legacy alias
39
npx storybook repro angular
40
```
41

42
### Link Command
43

44
Pull down a repository from URL or local directory, link it, and run Storybook for testing reproductions.
45

46
```bash { .api }
47
storybook link <repo-url-or-directory> [options]
48

49
Parameters:
50
  repo-url-or-directory                Target repository URL or local directory path
51

52
Options:
53
  --local                             Link a local directory already in your file system
54
  --no-start                          Start the storybook (default: true)
55
```
56

57
**Usage Examples:**
58

59
```bash
60
# Link and run remote repository
61
npx storybook link https://github.com/user/storybook-repro
62

63
# Link local directory
64
npx storybook link ./local-storybook-project --local
65

66
# Link without starting Storybook
67
npx storybook link https://github.com/user/repro --no-start
68

69
# Link local directory and start immediately
70
npx storybook link ../my-storybook-project --local
71
```
72

73
### Template System
74

75
The sandbox command provides access to extensive templates:
76

77
#### Framework Templates
78
- **React** - Create React App, Next.js, custom React setups
79
- **Vue** - Vue CLI, Nuxt.js, custom Vue configurations  
80
- **Angular** - Angular CLI projects with Storybook
81
- **Svelte** - SvelteKit and custom Svelte projects
82
- **Web Components** - Lit, Stencil, and other web component frameworks
83
- **HTML** - Plain HTML/CSS/JS projects
84
- **React Native** - React Native with Storybook
85

86
#### Builder Templates
87
- **Webpack 5** - Templates using Webpack 5 builder
88
- **Vite** - Templates using Vite builder for faster builds
89

90
#### Specialized Templates
91
- **TypeScript** - TypeScript-configured templates
92
- **Monorepo** - Monorepo setup examples
93
- **Custom Webpack** - Advanced Webpack configuration examples
94
- **Testing** - Templates with testing setup (Jest, Vitest)
95

96
### Template Organization
97

98
Templates are organized by release cadence:
99

100
```typescript { .api }
101
interface Template {
102
  name: string;
103
  script: string;
104
  cadence: TemplateCadence;
105
  skipTasks?: string[];
106
  inDevelopment?: boolean;
107
  expected: {
108
    framework: string;
109
    renderer: string;
110
    builder: string;
111
  };
112
}
113

114
type TemplateCadence = "ci" | "daily" | "weekly";
115
type TemplateKey = string;
116
```
117

118
#### Release Cadences
119
- **CI** - Tested on every commit, most stable
120
- **Daily** - Tested daily, generally stable
121
- **Weekly** - Tested weekly, may have issues
122

123
### Repository Linking
124

125
The link command supports various repository sources:
126

127
#### Remote Repositories
128
```bash
129
# GitHub repositories
130
npx storybook link https://github.com/storybookjs/storybook
131

132
# GitLab repositories  
133
npx storybook link https://gitlab.com/user/project
134

135
# Bitbucket repositories
136
npx storybook link https://bitbucket.org/user/repo
137

138
# Raw git URLs
139
npx storybook link git@github.com:user/repo.git
140
```
141

142
#### Local Directories
143
```bash
144
# Relative paths
145
npx storybook link ../my-project --local
146

147
# Absolute paths
148
npx storybook link /Users/dev/projects/storybook-app --local
149

150
# Current directory
151
npx storybook link . --local
152
```
153

154
### Sandbox Workflow
155

156
Complete workflow for sandbox creation:
157

158
1. **Template Selection** - Choose from available templates
159
2. **Download** - Pull template from repository
160
3. **Installation** - Install dependencies with detected package manager
161
4. **Configuration** - Set up Storybook if --init is enabled
162
5. **Launch** - Start development server (optional)
163

164
### Link Workflow
165

166
Complete workflow for repository linking:
167

168
1. **Repository Cloning** - Clone or copy repository
169
2. **Dependency Installation** - Install project dependencies
170
3. **Storybook Detection** - Detect existing Storybook configuration
171
4. **Link Setup** - Configure linking if needed
172
5. **Development Server** - Start Storybook (unless --no-start)
173

174
### Package Manager Integration
175

176
Both commands work with all supported package managers:
177

178
- **npm** - Standard npm workflows
179
- **Yarn Classic** - Yarn 1.x support
180
- **Yarn Berry** - Yarn 2+ with PnP support
181
- **pnpm** - pnpm with workspace support
182
- **Bun** - Bun package manager support
183

184
### Development Use Cases
185

186
#### Bug Reproduction
187
```bash
188
# Create minimal reproduction environment
189
npx storybook sandbox react --output bug-repro
190
cd bug-repro
191
# Add minimal code to reproduce issue
192
```
193

194
#### Feature Testing
195
```bash
196
# Test new features in sandbox
197
npx storybook sandbox vue --output feature-test
198
cd feature-test
199
# Install and test new addons or features
200
```
201

202
#### Framework Exploration
203
```bash
204
# Explore different framework setups
205
npx storybook sandbox angular --output angular-exploration
206
npx storybook sandbox svelte --output svelte-exploration
207
```
208

209
#### Contribution Testing
210
```bash
211
# Test contributions against existing projects
212
npx storybook link https://github.com/user/storybook-issue-repro
213
# Test your changes against the reproduction
214
```
215

216
### Programmatic Usage
217

218
```typescript { .api }
219
import { sandbox, link } from "@storybook/cli";
220

221
/**
222
 * Create sandbox programmatically
223
 * @param options - Sandbox configuration
224
 */
225
function sandbox(options: SandboxOptions): Promise<void>;
226

227
/**
228
 * Link repositories programmatically
229
 * @param options - Link configuration
230
 */
231
function link(options: LinkOptions): Promise<void>;
232

233
interface SandboxOptions {
234
  filterValue?: string;
235
  output?: string;
236
  branch?: string;
237
  init?: boolean;
238
  packageManager: PackageManagerName;
239
}
240

241
interface LinkOptions {
242
  target: string;
243
  local?: boolean;
244
  start: boolean;
245
}
246

247
/**
248
 * Execute shell commands with logging
249
 * @param command - Command to execute
250
 * @param options - Execution options
251
 * @param config - Additional configuration
252
 */
253
function exec(
254
  command: string, 
255
  options?: ExecOptions,
256
  config?: ExecConfig
257
): Promise<unknown>;
258
```
259

260
**Programmatic Examples:**
261

262
```typescript
263
import { sandbox, link } from "@storybook/cli";
264

265
// Create sandbox programmatically
266
await sandbox({
267
  filterValue: "react",
268
  output: "my-sandbox",
269
  init: true,
270
  packageManager: "npm"
271
});
272

273
// Link repository programmatically
274
await link({
275
  target: "https://github.com/user/repro",
276
  local: false,
277
  start: true
278
});
279
```
280

281
### Advanced Features
282

283
#### Custom Output Directories
284
```bash
285
# Organize sandboxes by purpose
286
npx storybook sandbox react --output sandboxes/react-testing
287
npx storybook sandbox vue --output sandboxes/vue-debugging
288
```
289

290
#### Template Filtering
291
```bash
292
# Filter by framework
293
npx storybook sandbox react
294

295
# Filter by builder  
296
npx storybook sandbox vite
297

298
# Filter by specific template name
299
npx storybook sandbox "react-typescript"
300
```
301

302
#### Selective Initialization
303
```bash
304
# Download template without Storybook setup
305
npx storybook sandbox react --no-init
306

307
# Manually initialize later
308
cd react-template
309
npx storybook@latest init
310
```