0
# CLI Commands
1

2
Command-line interface for React Styleguidist providing essential operations for building and serving styleguides. The CLI is ideal for integration with npm scripts, build processes, and CI/CD pipelines.
3

4
## Capabilities
5

6
### Build Command
7

8
Build a static styleguide for production deployment.
9

10
```bash { .api }
11
styleguidist build [options]
12

13
Options:
14
  --config <path>    Path to configuration file
15
  --verbose          Print detailed build information
16
```
17

18
**Usage Examples:**
19

20
```bash
21
# Build with default config (looks for styleguide.config.js)
22
styleguidist build
23

24
# Build with custom config file
25
styleguidist build --config ./custom-styleguide.config.js
26

27
# Build with verbose output for debugging
28
styleguidist build --verbose
29

30
# Build from npm script
31
npm run styleguide:build
32
```
33

34
**Example npm scripts:**
35

36
```json
37
{
38
  "scripts": {
39
    "styleguide:build": "styleguidist build",
40
    "styleguide:build:prod": "NODE_ENV=production styleguidist build --verbose",
41
    "styleguide:build:custom": "styleguidist build --config configs/styleguide.config.js"
42
  }
43
}
44
```
45

46
### Server Command
47

48
Start a development server with hot reloading for component development.
49

50
```bash { .api }
51
styleguidist server [options]
52

53
Options:
54
  --config <path>    Path to configuration file
55
  --port <number>    Port number for the development server
56
  --open             Open styleguide in default browser automatically
57
  --verbose          Print detailed server information
58
```
59

60
**Usage Examples:**
61

62
```bash
63
# Start server with default config and port (6060)
64
styleguidist server
65

66
# Start server on custom port
67
styleguidist server --port 8080
68

69
# Start server and open browser automatically
70
styleguidist server --open
71

72
# Start server with custom config
73
styleguidist server --config ./dev-styleguide.config.js
74

75
# Start server with verbose logging
76
styleguidist server --verbose
77

78
# Combine multiple options
79
styleguidist server --port 3000 --open --verbose
80
```
81

82
**Example npm scripts:**
83

84
```json
85
{
86
  "scripts": {
87
    "styleguide:dev": "styleguidist server",
88
    "styleguide:dev:open": "styleguidist server --open",
89
    "styleguide:dev:debug": "styleguidist server --verbose --port 9000",
90
    "styleguide:dev:custom": "styleguidist server --config configs/dev.config.js --open"
91
  }
92
}
93
```
94

95
### Help Command
96

97
Display usage information and available commands.
98

99
```bash { .api }
100
styleguidist help
101
# or
102
styleguidist --help
103
# or
104
styleguidist
105
```
106

107
**Output:**
108

109
```
110
Usage
111

112
    styleguidist <command> [<options>]
113

114
Commands
115

116
    build           Build style guide
117
    server          Run development server
118
    help            Display React Styleguidist help
119

120
Options
121

122
    --config        Config file path
123
    --port          Port to run development server on
124
    --open          Open Styleguidist in the default browser
125
    --verbose       Print debug information
126
```
127

128
## Configuration File Discovery
129

130
The CLI automatically discovers configuration files in the following order:
131

132
1. Path specified via `--config` option
133
2. `styleguide.config.js` in current directory
134
3. Default configuration (if no file found)
135

136
**Configuration file formats supported:**
137

138
```javascript
139
// styleguide.config.js - CommonJS
140
module.exports = {
141
  components: 'src/components/**/*.{js,jsx}',
142
  styleguideDir: 'dist/styleguide'
143
};
144

145
// styleguide.config.js - ESM (with .mjs extension or "type": "module")
146
export default {
147
  components: 'src/components/**/*.{js,jsx}',
148
  styleguideDir: 'dist/styleguide'
149
};
150
```
151

152
## Environment Variables
153

154
The CLI respects several environment variables:
155

156
```bash { .api }
157
NODE_ENV=production    # Affects webpack optimizations and defaults
158
PORT=8080             # Default port if --port not specified (server command)
159
BROWSER=firefox       # Browser for --open option (server command)
160
```
161

162
**Usage Examples:**
163

164
```bash
165
# Production build
166
NODE_ENV=production styleguidist build
167

168
# Development server with custom browser
169
BROWSER=chrome styleguidist server --open
170

171
# Server with environment port
172
PORT=9090 styleguidist server
173
```
174

175
## Integration Patterns
176

177
### CI/CD Pipeline Integration
178

179
```yaml
180
# GitHub Actions example
181
name: Build Styleguide
182
on: [push]
183
jobs:
184
  styleguide:
185
    runs-on: ubuntu-latest
186
    steps:
187
      - uses: actions/checkout@v2
188
      - uses: actions/setup-node@v2
189
        with:
190
          node-version: '16'
191
      - run: npm ci
192
      - run: npx styleguidist build --verbose
193
      - uses: actions/upload-artifact@v2
194
        with:
195
          name: styleguide
196
          path: styleguide/
197
```
198

199
### Docker Integration
200

201
```dockerfile
202
# Dockerfile for styleguide development
203
FROM node:16-alpine
204
WORKDIR /app
205
COPY package*.json ./
206
RUN npm ci
207
COPY . .
208
EXPOSE 6060
209
CMD ["npx", "styleguidist", "server", "--port", "6060"]
210
```
211

212
### Development Workflow
213

214
```bash
215
# Start development with file watching
216
styleguidist server --open &
217
DEV_PID=$!
218

219
# Build for testing
220
styleguidist build
221

222
# Cleanup
223
kill $DEV_PID
224
```
225

226
### Package.json Scripts Organization
227

228
```json
229
{
230
  "scripts": {
231
    // Development
232
    "dev": "styleguidist server --open",
233
    "dev:verbose": "styleguidist server --verbose",
234
    
235
    // Building
236
    "build": "styleguidist build",
237
    "build:verbose": "styleguidist build --verbose",
238
    "prebuild": "rm -rf styleguide",
239
    
240
    // Testing
241
    "test:styleguide": "npm run build && serve -s styleguide -p 8080",
242
    
243
    // Deployment
244
    "deploy:styleguide": "npm run build && aws s3 sync styleguide/ s3://my-styleguide-bucket/",
245
    
246
    // Combined workflows
247
    "dev:full": "concurrently \"npm run dev\" \"npm run test:watch\"",
248
    "ci:styleguide": "npm run build && npm run test:styleguide"
249
  }
250
}
251
```
252

253
## Error Handling
254

255
The CLI provides detailed error messages for common issues:
256

257
**Configuration Errors:**
258
```bash
259
$ styleguidist build --config missing.js
260
Error: Styleguidist config not found: /path/to/missing.js
261

262
Learn how to configure your style guide:
263
https://react-styleguidist.js.org/docs/configuration
264
```
265

266
**Port Conflicts:**
267
```bash
268
$ styleguidist server --port 3000
269
Error: Another server is running at port 3000 already. Please stop it or change the default port to continue.
270
```
271

272
**Webpack Errors:**
273
```bash
274
$ styleguidist build --verbose
275
Failed to compile
276

277
Module not found: Can't resolve './NonExistentComponent' in '/src/components'
278
```
279

280
## Advanced CLI Usage
281

282
**Custom Configuration with Environment Variables:**
283

284
```bash
285
# Use different configs per environment
286
STYLEGUIDE_ENV=development styleguidist server --config configs/styleguide.${STYLEGUIDE_ENV}.js
287

288
# Override specific config values
289
COMPONENTS_PATTERN="src/**/*.tsx" styleguidist build
290
```
291

292
**Programmatic CLI Usage:**
293

294
```javascript
295
const { spawn } = require('child_process');
296

297
function buildStyleguide(options = {}) {
298
  const args = ['build'];
299
  if (options.config) args.push('--config', options.config);
300
  if (options.verbose) args.push('--verbose');
301
  
302
  return new Promise((resolve, reject) => {
303
    const child = spawn('styleguidist', args, { stdio: 'inherit' });
304
    child.on('close', (code) => {
305
      if (code === 0) resolve();
306
      else reject(new Error(`CLI exited with code ${code}`));
307
    });
308
  });
309
}
310
```