0
# CLI Commands
1

2
Command-line interface for development, building, and deployment workflows. The CLI provides three main commands for different stages of the component development lifecycle.
3

4
## Capabilities
5

6
### Serve Command
7

8
Starts the development server with hot module reloading for interactive component development.
9

10
```bash { .api }
11
ladle serve [options]
12
# Alias: ladle dev [options]
13
```
14

15
**Options:**
16

17
- `--host <host>` - Specify host address (default: localhost)
18
- `--port <port>` - Specify port number (default: 61000)
19
- `--stories <pattern>` - Glob pattern for story files (default: "src/**/*.stories.{js,jsx,ts,tsx,mdx}")
20
- `--theme <theme>` - Default theme ("light" | "dark" | "auto")
21
- `--config <path>` - Path to config file (default: ".ladle/config.mjs")
22
- `--viteConfig <path>` - Path to Vite config file
23
- `--base <path>` - Base path for URLs
24
- `--mode <mode>` - Environment mode
25
- `--noWatch` - Disable file watching
26

27
**Usage Examples:**
28

29
```bash
30
# Start development server on default port
31
ladle serve
32

33
# Start with custom port and host
34
ladle serve --port 3000 --host 0.0.0.0
35

36
# Use custom story pattern
37
ladle serve --stories "components/**/*.story.tsx"
38

39
# Start in dark theme mode
40
ladle serve --theme dark
41
```
42

43
### Build Command
44

45
Builds a static production version of the component library for deployment.
46

47
```bash { .api }
48
ladle build [options]
49
```
50

51
**Options:**
52

53
- `--outDir <directory>` - Output directory for build files (default: "build")
54
- `--stories <pattern>` - Glob pattern for story files
55
- `--theme <theme>` - Default theme for production build
56
- `--config <path>` - Path to config file
57
- `--viteConfig <path>` - Path to Vite config file
58
- `--base <path>` - Base path for URLs in production
59
- `--mode <mode>` - Build mode (default: "production")
60

61
**Usage Examples:**
62

63
```bash
64
# Build to default directory
65
ladle build
66

67
# Build to custom directory
68
ladle build --outDir dist
69

70
# Build with custom base path for CDN deployment
71
ladle build --base /my-components/
72

73
# Build with specific theme
74
ladle build --theme light
75
```
76

77
**Return Behavior:**
78
The build command returns a boolean indicating success (true) or failure (false) when used programmatically.
79

80
### Preview Command
81

82
Starts a preview server to test the built static files locally before deployment.
83

84
```bash { .api }
85
ladle preview [options]
86
```
87

88
**Options:**
89

90
- `--outDir <directory>` - Directory containing built files (default: "build")
91
- `--host <host>` - Preview server host
92
- `--port <port>` - Preview server port (default: 8080)
93
- `--config <path>` - Path to config file
94
- `--viteConfig <path>` - Path to Vite config file
95
- `--base <path>` - Base path for URLs
96
- `--mode <mode>` - Preview mode
97

98
**Usage Examples:**
99

100
```bash
101
# Preview built files on default port
102
ladle preview
103

104
# Preview on custom port
105
ladle preview --port 9000
106

107
# Preview files from custom build directory
108
ladle preview --outDir dist
109
```
110

111
## Command Line Integration
112

113
### Global Installation
114

115
```bash
116
# Install globally for system-wide access
117
npm install -g @ladle/react
118

119
# Use from anywhere
120
ladle serve
121
```
122

123
### Local Installation
124

125
```bash
126
# Install as dev dependency
127
npm install --save-dev @ladle/react
128

129
# Use via npm scripts
130
npm run ladle serve
131

132
# Or via npx
133
npx ladle serve
134
```
135

136
### Package Scripts Integration
137

138
Add Ladle commands to your `package.json`:
139

140
```json
141
{
142
  "scripts": {
143
    "dev": "ladle serve",
144
    "build-components": "ladle build",
145
    "preview-components": "ladle preview",
146
    "dev:components": "ladle serve --port 3001"
147
  }
148
}
149
```
150

151
## Configuration Integration
152

153
All CLI commands respect configuration from `.ladle/config.mjs`:
154

155
```javascript
156
// .ladle/config.mjs
157
export default {
158
  stories: "src/**/*.stories.{js,jsx,ts,tsx}",
159
  port: 3000,
160
  outDir: "component-docs",
161
  theme: "dark"
162
};
163
```
164

165
CLI options override configuration file settings when provided.