0
# Programmatic API
1

2
Node.js API for integrating Ladle functionality into custom build processes, development workflows, and automation scripts. Each function corresponds to a CLI command but provides programmatic control.
3

4
## Capabilities
5

6
### Serve API
7

8
Starts the development server programmatically with the same functionality as the CLI serve command.
9

10
```typescript { .api }
11
import serve from "@ladle/react/serve";
12

13
/**
14
 * Start development server programmatically
15
 * @param params - Optional CLI parameters
16
 * @returns Promise that resolves when server starts
17
 */
18
function serve(params?: CLIParams): Promise<void>;
19

20
interface CLIParams {
21
  host?: string;
22
  port?: number;
23
  stories?: string;
24
  theme?: "light" | "dark" | "auto";
25
  config?: string;
26
  viteConfig?: string;
27
  base?: string;
28
  mode?: string;
29
  noWatch?: boolean;
30
}
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import serve from "@ladle/react/serve";
37

38
// Start with default settings
39
await serve();
40

41
// Start with custom configuration
42
await serve({
43
  port: 3000,
44
  host: "0.0.0.0",
45
  stories: "components/**/*.story.tsx",
46
  theme: "dark"
47
});
48

49
// Integration in custom dev script
50
async function startDevelopment() {
51
  console.log("Starting component development server...");
52
  try {
53
    await serve({ port: 4000, noWatch: false });
54
    console.log("Server started successfully");
55
  } catch (error) {
56
    console.error("Failed to start server:", error);
57
  }
58
}
59
```
60

61
### Build API
62

63
Builds the static production version programmatically, returning a boolean indicating success or failure.
64

65
```typescript { .api }
66
import build from "@ladle/react/build";
67

68
/**
69
 * Build static production app programmatically
70
 * @param params - Optional CLI parameters
71
 * @returns Promise resolving to true on success, false on failure
72
 */
73
function build(params?: CLIParams): Promise<boolean>;
74

75
interface CLIParams {
76
  outDir?: string;
77
  stories?: string;
78
  theme?: "light" | "dark" | "auto";
79
  config?: string;
80
  viteConfig?: string;
81
  base?: string;
82
  mode?: string;
83
}
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import build from "@ladle/react/build";
90

91
// Build with default settings
92
const success = await build();
93
if (success) {
94
  console.log("Build completed successfully");
95
} else {
96
  console.error("Build failed");
97
  process.exit(1);
98
}
99

100
// Build with custom configuration
101
const buildResult = await build({
102
  outDir: "dist/components",
103
  base: "/my-app/components/",
104
  theme: "light"
105
});
106

107
// Integration in CI/CD pipeline
108
async function buildForProduction() {
109
  const result = await build({
110
    outDir: process.env.BUILD_DIR || "build",
111
    base: process.env.BASE_PATH || "/",
112
    mode: "production"
113
  });
114
  
115
  if (!result) {
116
    throw new Error("Component build failed");
117
  }
118
  
119
  return result;
120
}
121
```
122

123
### Preview API
124

125
Starts the preview server programmatically to serve built static files.
126

127
```typescript { .api }
128
import preview from "@ladle/react/preview";
129

130
/**
131
 * Start preview server programmatically
132
 * @param params - Optional CLI parameters
133
 * @returns Promise that resolves when server starts
134
 */
135
function preview(params?: CLIParams): Promise<void>;
136

137
interface CLIParams {
138
  outDir?: string;
139
  host?: string;
140
  port?: number;
141
  config?: string;
142
  viteConfig?: string;
143
  base?: string;
144
  mode?: string;
145
}
146
```
147

148
**Usage Examples:**
149

150
```typescript
151
import preview from "@ladle/react/preview";
152

153
// Preview with default settings
154
await preview();
155

156
// Preview with custom configuration
157
await preview({
158
  port: 8080,
159
  host: "0.0.0.0",
160
  outDir: "dist/components"
161
});
162

163
// Integration with testing workflow
164
async function previewForTesting() {
165
  await preview({
166
    port: 9000,
167
    host: "localhost"
168
  });
169
  
170
  // Run E2E tests against preview server
171
  // Server will be running at http://localhost:9000
172
}
173
```
174

175
### Meta API
176

177
Retrieves metadata about stories and configuration for integration with other tools.
178

179
```typescript { .api }
180
import meta from "@ladle/react/meta";
181

182
/**
183
 * Get metadata about stories and configuration
184
 * @returns Story metadata and configuration information
185
 */
186
function meta(): any;
187
```
188

189
**Usage Examples:**
190

191
```typescript
192
import meta from "@ladle/react/meta";
193

194
// Get story metadata
195
const storyMetadata = meta();
196
console.log("Available stories:", storyMetadata);
197

198
// Use metadata for custom tooling
199
function analyzeStories() {
200
  const metadata = meta();
201
  
202
  // Process metadata for documentation generation,
203
  // test automation, or other custom workflows
204
  return metadata;
205
}
206
```
207

208
### MSW Node Integration
209

210
Server setup for Node.js environments when using Mock Service Worker in stories.
211

212
```typescript { .api }
213
import { setupServer } from "@ladle/react/msw-node";
214

215
/**
216
 * MSW server setup function from msw/node
217
 * Used for server-side mocking in Node.js environments
218
 */
219
const setupServer: typeof import("msw/node").setupServer;
220
```
221

222
**Usage Examples:**
223

224
```typescript
225
import { setupServer } from "@ladle/react/msw-node";
226
import { handlers } from "./mocks/handlers";
227

228
// Setup MSW server for Node.js testing
229
const server = setupServer(...handlers);
230

231
// Start server before tests
232
beforeAll(() => server.listen());
233

234
// Reset handlers between tests
235
afterEach(() => server.resetHandlers());
236

237
// Clean up after tests
238
afterAll(() => server.close());
239
```
240

241
## Integration Patterns
242

243
### Custom Development Workflow
244

245
```typescript
246
import serve from "@ladle/react/serve";
247
import build from "@ladle/react/build";
248

249
async function customWorkflow() {
250
  // Start development server
251
  console.log("Starting development mode...");
252
  await serve({
253
    port: 3000,
254
    stories: "src/**/*.stories.tsx"
255
  });
256
  
257
  // In separate process or on command, build production
258
  console.log("Building for production...");
259
  const buildSuccess = await build({
260
    outDir: "build",
261
    base: "/components/"
262
  });
263
  
264
  if (buildSuccess) {
265
    console.log("Workflow completed successfully");
266
  }
267
}
268
```
269

270
### CI/CD Integration
271

272
```typescript
273
import build from "@ladle/react/build";
274

275
async function cicdBuild() {
276
  try {
277
    const success = await build({
278
      outDir: process.env.OUTPUT_DIR,
279
      base: process.env.BASE_URL,
280
      mode: "production"
281
    });
282
    
283
    if (!success) {
284
      process.exit(1);
285
    }
286
    
287
    console.log("Build completed for deployment");
288
  } catch (error) {
289
    console.error("Build failed:", error);
290
    process.exit(1);
291
  }
292
}
293
```