0
# Programmatic API
1

2
Shadow-CLJS provides a comprehensive programmatic API for integrating build operations into custom tooling and automation scripts. The API mirrors CLI functionality while providing more granular control.
3

4
## Core Namespaces
5

6
### shadow.cljs.devtools.api
7

8
Primary namespace for programmatic build operations.
9

10
```clojure
11
(require '[shadow.cljs.devtools.api :as shadow])
12
```
13

14
## Capabilities
15

16
### Compilation Functions
17

18
Core build compilation functions for automated build processes.
19

20
```clojure { .api }
21
(shadow/compile build-id)
22
;; Compiles a build once and returns compilation result
23
;; Args: build-id (keyword) - Build identifier from shadow-cljs.edn
24
;; Returns: map with compilation status and metadata
25

26
(shadow/compile build-id options)
27
;; Compiles with additional options
28
;; Args: build-id (keyword), options (map)
29
;; Options: {:debug boolean, :pseudo-names boolean, :source-maps boolean}
30
;; Returns: compilation result map
31

32
(shadow/watch build-id)
33
;; Starts watching a build for changes
34
;; Args: build-id (keyword)
35
;; Returns: watch instance map
36

37
(shadow/watch build-id options)
38
;; Starts watching with options
39
;; Args: build-id (keyword), options (map)
40
;; Options: {:verbose boolean, :sync boolean}
41
;; Returns: watch instance map
42

43
(shadow/release build-id)
44
;; Compiles with optimizations for production
45
;; Args: build-id (keyword)
46
;; Returns: compilation result map
47

48
(shadow/release build-id options)
49
;; Release compilation with options
50
;; Args: build-id (keyword), options (map)
51
;; Options: {:debug boolean, :source-maps boolean}
52
;; Returns: compilation result map
53

54
(shadow/check build-id)
55
;; Checks compilation without output
56
;; Args: build-id (keyword)
57
;; Returns: check result map with errors and warnings
58
```
59

60
**Usage Examples:**
61

62
```clojure
63
(require '[shadow.cljs.devtools.api :as shadow])
64

65
;; Simple compilation
66
(shadow/compile :app)
67

68
;; Compilation with debug options
69
(shadow/compile :app {:debug true :source-maps true})
70

71
;; Start watching for development
72
(shadow/watch :app {:verbose true})
73

74
;; Production build
75
(shadow/release :app)
76

77
;; Check for errors without compiling
78
(let [result (shadow/check :app)]
79
  (when-not (:success result)
80
    (println "Compilation errors:" (:errors result))))
81
```
82

83
### REPL Functions
84

85
Interactive development and debugging functions.
86

87
```clojure { .api }
88
(shadow/repl build-id)
89
;; Starts a REPL connected to the specified build
90
;; Args: build-id (keyword)
91
;; Returns: REPL instance map
92

93
(shadow/node-repl)
94
;; Starts a Node.js REPL for server-side development
95
;; Args: none
96
;; Returns: Node REPL instance map
97

98
(shadow/node-repl options)
99
;; Node.js REPL with configuration options
100
;; Args: options (map)
101
;; Options: {:port number, :host string}
102
;; Returns: Node REPL instance map
103

104
(shadow/browser-repl)
105
;; Starts a browser REPL for general ClojureScript development
106
;; Args: none
107
;; Returns: browser REPL instance map
108

109
(shadow/browser-repl options)
110
;; Browser REPL with options
111
;; Args: options (map)
112
;; Options: {:port number, :host string, :ssl boolean}
113
;; Returns: browser REPL instance map
114
```
115

116
**Usage Examples:**
117

118
```clojure
119
;; Start build-specific REPL
120
(shadow/repl :app)
121

122
;; Start Node.js REPL on custom port
123
(shadow/node-repl {:port 8081})
124

125
;; Start browser REPL with SSL
126
(shadow/browser-repl {:ssl true :port 9000})
127
```
128

129
### Runtime Management
130

131
Functions for managing build runtimes and connections.
132

133
```clojure { .api }
134
(shadow/get-runtime!)
135
;; Gets the current runtime instance
136
;; Args: none
137
;; Returns: runtime map
138

139
(shadow/get-runtime! build-id)
140
;; Gets the runtime instance for a build
141
;; Args: build-id (keyword)
142
;; Returns: runtime map or nil if not found
143

144
(shadow/with-runtime build-id body)
145
;; Executes code within a runtime context
146
;; Args: build-id (keyword), body (any)
147
;; Returns: execution result
148

149
(shadow/active-builds)
150
;; Returns list of currently active builds
151
;; Args: none
152
;; Returns: vector of build-id keywords
153

154
(shadow/get-build-ids)
155
;; Returns all configured build IDs from shadow-cljs.edn
156
;; Args: none
157
;; Returns: set of build-id keywords
158

159
(shadow/worker-running? build-id)
160
;; Checks if a build worker is currently running
161
;; Args: build-id (keyword)
162
;; Returns: boolean
163

164
(shadow/repl-runtimes)
165
;; Gets all available REPL runtimes
166
;; Args: none
167
;; Returns: map of runtime-id to runtime info
168
```
169

170
**Usage Examples:**
171

172
```clojure
173
;; Check active builds
174
(def builds (shadow/active-builds))
175
(println "Active builds:" builds)
176

177
;; Get runtime for specific build
178
(when-let [runtime (shadow/get-runtime! :app)]
179
  (println "Runtime info:" runtime))
180

181
;; Execute in runtime context
182
(shadow/with-runtime :app
183
  (js/console.log "Hello from runtime!"))
184

185
;; Check if worker is running
186
(if (shadow/worker-running? :app)
187
  (println "Build worker is active")
188
  (println "Build worker is stopped"))
189
```
190

191
### Server Management
192

193
Development server control functions.
194

195
```clojure { .api }
196
(shadow/start-server!)
197
;; Starts the Shadow-CLJS development server
198
;; Args: none
199
;; Returns: server instance map
200

201
(shadow/start-server! config)
202
;; Starts server with configuration
203
;; Args: config (map)
204
;; Config: {:port number, :host string, :ssl boolean}
205
;; Returns: server instance map
206

207
(shadow/stop-server!)
208
;; Stops the development server
209
;; Args: none
210
;; Returns: stop result map
211

212
(shadow/server-running?)
213
;; Checks if development server is running
214
;; Args: none
215
;; Returns: boolean
216

217
(shadow/get-server-instance)
218
;; Gets the current server instance
219
;; Args: none
220
;; Returns: server instance map or nil
221
```
222

223
**Usage Examples:**
224

225
```clojure
226
;; Start development server
227
(shadow/start-server!)
228

229
;; Start server on custom port
230
(shadow/start-server! {:port 8080 :host "0.0.0.0"})
231

232
;; Check server status
233
(when (shadow/server-running?)
234
  (println "Server is running"))
235

236
;; Stop server
237
(shadow/stop-server!)
238
```
239

240
### Watch Management
241

242
Functions for controlling watch processes and autobuild behavior.
243

244
```clojure { .api }
245
(shadow/watch-compile! build-id)
246
;; Manually trigger recompilation for a watch build
247
;; Args: build-id (keyword)
248
;; Returns: :ok or :watch-not-running
249

250
(shadow/watch-compile-all!)
251
;; Trigger recompilation for all running watch builds
252
;; Args: none
253
;; Returns: :ok
254

255
(shadow/watch-set-autobuild! build-id toggle)
256
;; Enable or disable autobuild for a watch build
257
;; Args: build-id (keyword), toggle (boolean)
258
;; Returns: :ok or :watch-not-running
259
```
260

261
**Usage Examples:**
262

263
```clojure
264
;; Manually compile a watch build
265
(shadow/watch-compile! :app)
266

267
;; Compile all active watch builds
268
(shadow/watch-compile-all!)
269

270
;; Enable autobuild for a watch
271
(shadow/watch-set-autobuild! :app true)
272

273
;; Disable autobuild for a watch
274
(shadow/watch-set-autobuild! :app false)
275
```
276

277
### Dependency Management
278

279
Functions for managing project dependencies at runtime.
280

281
```clojure { .api }
282
(shadow/reload-deps!)
283
;; Reload project dependencies without restarting
284
;; Args: none
285
;; Returns: ::loaded, ::no-changes, ::conflicts, or ::standalone-only
286

287
(shadow/reload-deps! opts)
288
;; Reload dependencies with options
289
;; Args: opts (map) - {:deps deps-map, :ignore-conflicts boolean}
290
;; Returns: reload result keyword
291
```
292

293
**Usage Examples:**
294

295
```clojure
296
;; Simple dependency reload
297
(shadow/reload-deps!)
298

299
;; Reload with specific dependencies
300
(shadow/reload-deps! {:deps {'some/lib {:mvn/version "1.2.3"}}})
301

302
;; Ignore version conflicts
303
(shadow/reload-deps! {:ignore-conflicts true})
304
```
305

306
## Build System API
307

308
### shadow.build.api
309

310
Lower-level build system functions for advanced use cases.
311

312
```clojure { .api }
313
(require '[shadow.build.api :as build])
314

315
(build/compile-stage build-state stage options)
316
;; Executes a specific compilation stage
317
;; Args: build-state (map), stage (keyword), options (map)
318
;; Returns: updated build-state map
319

320
(build/configure-modules build-state modules-config)
321
;; Configures build modules
322
;; Args: build-state (map), modules-config (map)
323
;; Returns: updated build-state map
324

325
(build/compile-modules build-state)
326
;; Compiles configured modules
327
;; Args: build-state (map)
328
;; Returns: updated build-state map
329

330
(build/optimize-modules build-state optimizer-options)
331
;; Applies optimizations to compiled modules
332
;; Args: build-state (map), optimizer-options (map)
333
;; Returns: updated build-state map
334

335
(build/flush-modules-to-disk build-state output-dir)
336
;; Writes compiled modules to disk
337
;; Args: build-state (map), output-dir (string)
338
;; Returns: updated build-state map
339

340
(build/get-output build-state)
341
;; Gets compilation output information
342
;; Args: build-state (map)
343
;; Returns: output map with file paths and metadata
344
```
345

346
## Configuration API
347

348
### shadow.cljs.devtools.config
349

350
Configuration management and validation functions.
351

352
```clojure { .api }
353
(require '[shadow.cljs.devtools.config :as config])
354

355
(config/load-cljs-edn)
356
;; Loads shadow-cljs.edn from current directory
357
;; Args: none
358
;; Returns: configuration map
359

360
(config/load-cljs-edn config-file)
361
;; Loads configuration from specific file
362
;; Args: config-file (string path)
363
;; Returns: configuration map
364

365
(config/get-config)
366
;; Gets current global configuration
367
;; Args: none
368
;; Returns: configuration map
369

370
(config/get-build-config build-id)
371
;; Gets configuration for specific build
372
;; Args: build-id (keyword)
373
;; Returns: build configuration map
374

375
(config/normalize-config config)
376
;; Normalizes configuration structure
377
;; Args: config (map)
378
;; Returns: normalized configuration map
379

380
(config/validate-config config)
381
;; Validates configuration structure and values
382
;; Args: config (map)
383
;; Returns: validation result map
384
```
385

386
**Usage Examples:**
387

388
```clojure
389
(require '[shadow.cljs.devtools.config :as config])
390

391
;; Load and validate configuration
392
(let [config (config/load-cljs-edn)]
393
  (if-let [validation (config/validate-config config)]
394
    (println "Config valid")
395
    (println "Config errors:" validation)))
396

397
;; Get build-specific configuration
398
(def app-config (config/get-build-config :app))
399
(println "Output directory:" (:output-dir app-config))
400
```