0
# Build Configuration
1

2
Shadow-CLJS uses a declarative configuration system through the `shadow-cljs.edn` file. This file defines project dependencies, build targets, and development server settings using Extensible Data Notation (EDN) format.
3

4
## Configuration File Structure
5

6
### shadow-cljs.edn
7

8
The primary configuration file located in the project root.
9

10
```clojure { .api }
11
{:source-paths [string]              ;; Vector of source directory paths
12
 :resource-paths [string]            ;; Vector of resource directory paths  
13
 :dependencies [dependency-vector]   ;; ClojureScript dependencies
14
 :dev-dependencies [dependency-vector] ;; Development-only dependencies
15
 :builds {build-id build-config}     ;; Map of build configurations
16
 :dev-http {port config}             ;; Development HTTP server settings
17
 :nrepl {:port number :host string}  ;; nREPL server configuration
18
 :socket-repl {:port number :host string} ;; Socket REPL configuration
19
 :deps true                          ;; Enable deps.edn integration
20
 :user-config map                    ;; User-specific configuration
21
 :closure-defines map                ;; Global closure defines
22
 :compiler-options map               ;; Global compiler options
23
 :js-options map                     ;; JavaScript processing options}
24
```
25

26
**Usage Example:**
27

28
```clojure
29
{:source-paths ["src/main" "src/shared"]
30
 :resource-paths ["resources"]
31
 :dependencies [[reagent "1.1.1"]
32
                [re-frame "1.2.0"]]
33
 :dev-dependencies [[binaryage/devtools "1.0.4"]]
34
 
35
 :builds
36
 {:app {:target :browser
37
        :output-dir "public/js"
38
        :asset-path "/js"
39
        :modules {:main {:init-fn myapp.core/init
40
                        :preloads [devtools.preload]}}}
41
  
42
  :test {:target :node-test
43
         :output-to "out/test.js"
44
         :autorun true}}
45
 
46
 :dev-http {8080 "public"
47
            9000 {:root "resources/public"
48
                  :push-state/index "index.html"}}
49
 
50
 :nrepl {:port 8777}}
51
```
52

53
## Capabilities
54

55
### Source Path Configuration
56

57
Defines where Shadow-CLJS looks for ClojureScript source files.
58

59
```clojure { .api }
60
:source-paths [string]
61
;; Vector of directory paths containing .cljs, .cljc, and .clj files
62
;; Paths are relative to project root
63
;; Default: ["src"]
64

65
:resource-paths [string]  
66
;; Vector of directory paths containing static resources
67
;; Resources are available on classpath
68
;; Default: ["resources"]
69
```
70

71
**Usage Examples:**
72

73
```clojure
74
;; Basic source configuration
75
{:source-paths ["src"]}
76

77
;; Multiple source directories
78
{:source-paths ["src/main" "src/shared" "src/client"]}
79

80
;; Source and resource paths
81
{:source-paths ["src"]
82
 :resource-paths ["resources" "assets"]}
83
```
84

85
### Dependency Configuration
86

87
Manages ClojureScript and Clojure dependencies for the project.
88

89
```clojure { .api }
90
:dependencies [dependency-vector]
91
;; Vector of dependency specifications [lib-name version & options]
92
;; lib-name: symbol representing library name
93
;; version: string version specification
94
;; options: optional map with :exclusions, :scope, etc.
95

96
:dev-dependencies [dependency-vector]
97
;; Dependencies only loaded during development
98
;; Not included in production builds
99
;; Same format as :dependencies
100
```
101

102
**Usage Examples:**
103

104
```clojure
105
;; Basic dependencies
106
{:dependencies [[org.clojure/clojurescript "1.11.54"]
107
                [reagent "1.1.1"]
108
                [re-frame "1.2.0"]]}
109

110
;; Dependencies with exclusions
111
{:dependencies [[some-lib "1.0.0" :exclusions [conflicting-dep]]]}
112

113
;; Development dependencies
114
{:dev-dependencies [[binaryage/devtools "1.0.4"]
115
                    [day8.re-frame/re-frame-10x "1.2.2"]]}
116
```
117

118
### Build Configuration
119

120
Core build settings that define how ClojureScript code is compiled.
121

122
```clojure { .api }
123
:builds {build-id build-config}
124
;; Map where keys are build identifiers (keywords)
125
;; Values are build configuration maps
126

127
;; Build configuration structure:
128
{:target keyword                     ;; Build target type
129
 :output-dir string                  ;; Output directory path
130
 :output-to string                   ;; Single output file path (some targets)
131
 :asset-path string                  ;; Public path for generated assets
132
 :public-dir string                  ;; Public directory for assets
133
 :modules map                        ;; Module configuration for code splitting
134
 :entries [namespace-symbol]         ;; Entry point namespaces
135
 :main namespace-symbol              ;; Main namespace (some targets)
136
 :init-fn symbol                     ;; Initialization function
137
 :dev map                           ;; Development-specific options
138
 :release map                       ;; Release/production options
139
 :compiler-options map              ;; ClojureScript compiler options
140
 :js-options map                    ;; JavaScript processing options
141
 :closure-defines map               ;; Closure compiler defines
142
 :devtools map                      ;; Development tools configuration}
143
```
144

145
**Usage Examples:**
146

147
```clojure
148
;; Browser application build
149
{:builds
150
 {:app {:target :browser
151
        :output-dir "public/js"
152
        :asset-path "/js"
153
        :modules {:main {:init-fn myapp.core/init
154
                        :depends-on #{:shared}}
155
                  :shared {:entries [myapp.util]}}
156
        :dev {:preloads [devtools.preload]
157
              :console-support true}
158
        :release {:module-hash-names true
159
                  :optimize-constants true}}}}
160

161
;; Node.js script build  
162
{:builds
163
 {:server {:target :node-script
164
           :main myapp.server/main
165
           :output-to "server.js"
166
           :devtools {:enabled false}}}}
167
```
168

169
### Development Server Configuration
170

171
HTTP server settings for serving static files and development assets.
172

173
```clojure { .api }
174
:dev-http {port config}
175
;; Map where keys are port numbers
176
;; Values are either strings (root directory) or configuration maps
177

178
;; Server configuration options:
179
{:root string                        ;; Root directory to serve
180
 :push-state/index string           ;; SPA index file for pushState routing
181
 :push-state/headers map            ;; Additional headers for pushState responses
182
 :ssl-port number                   ;; HTTPS port
183
 :ssl-cert string                   ;; SSL certificate file path
184
 :ssl-key string                    ;; SSL key file path
185
 :handler symbol                    ;; Custom Ring handler function
186
 :middleware [symbol]               ;; Ring middleware functions
187
 :proxy-url string                  ;; Proxy backend URL
188
 :proxy-exclude-patterns [string]   ;; Paths to exclude from proxying}
189
```
190

191
**Usage Examples:**
192

193
```clojure
194
;; Simple static file server
195
{:dev-http {8080 "public"}}
196

197
;; Multiple ports with different configurations
198
{:dev-http {8080 "public"
199
            9000 {:root "resources/public"
200
                  :push-state/index "index.html"}}}
201

202
;; SSL configuration
203
{:dev-http {8080 "public"
204
            8443 {:root "public"
205
                  :ssl-cert "cert.pem"
206
                  :ssl-key "key.pem"}}}
207

208
;; Proxy configuration for API backend
209
{:dev-http {3000 {:root "public"
210
                  :proxy-url "http://localhost:8080"
211
                  :proxy-exclude-patterns ["/api"]}}}
212
```
213

214
### REPL Configuration
215

216
Settings for interactive development environments.
217

218
```clojure { .api }
219
:nrepl {:port number                 ;; nREPL server port
220
        :host string                 ;; nREPL server host
221
        :middleware [symbol]         ;; Additional nREPL middleware
222
        :init-ns symbol             ;; Initial namespace for REPL session}
223

224
:socket-repl {:port number           ;; Socket REPL port  
225
              :host string           ;; Socket REPL host
226
              :accept symbol         ;; Accept function symbol}
227
```
228

229
**Usage Examples:**
230

231
```clojure
232
;; Basic nREPL configuration
233
{:nrepl {:port 8777}}
234

235
;; nREPL with custom middleware
236
{:nrepl {:port 8777
237
         :host "0.0.0.0"
238
         :middleware [cider.piggieback/wrap-cljs-repl]
239
         :init-ns myapp.repl}}
240

241
;; Socket REPL configuration
242
{:socket-repl {:port 8888
243
               :accept cljs.server.node/repl}}
244
```
245

246
### Global Compiler Options
247

248
ClojureScript compiler settings applied to all builds.
249

250
```clojure { .api }
251
:compiler-options map
252
;; Global ClojureScript compiler options
253
;; Individual builds can override these settings
254

255
;; Common compiler options:
256
{:optimizations keyword              ;; :none, :whitespace, :simple, :advanced
257
 :pretty-print boolean              ;; Format output for readability
258
 :pseudo-names boolean              ;; Use readable names in optimized output
259
 :source-map boolean                ;; Generate source maps
260
 :source-map-path string            ;; Source map file path
261
 :target keyword                    ;; :nodejs, :webworker, :nashorn
262
 :language-in keyword               ;; Input language level
263
 :language-out keyword              ;; Output language level
264
 :foreign-libs [map]                ;; External JavaScript libraries
265
 :externs [string]                  ;; Extern files for advanced compilation
266
 :modules map                       ;; Module configuration
267
 :main symbol                       ;; Main entry point
268
 :output-wrapper boolean            ;; Wrap output in function
269
 :hashbang boolean                 ;; Include hashbang in Node.js output
270
 :npm-deps map                     ;; NPM dependency overrides
271
 :install-deps boolean             ;; Auto-install NPM dependencies}
272

273
:closure-defines map
274
;; Global closure compiler defines
275
;; Available to all builds and can be overridden per build
276

277
:js-options map  
278
;; JavaScript processing options
279
{:resolve map                       ;; Module resolution configuration
280
 :packages map                      ;; Package-specific settings
281
 :entry-keys [keyword]              ;; Package.json entry point keys}
282
```
283

284
**Usage Examples:**
285

286
```clojure
287
;; Global compiler options
288
{:compiler-options {:optimizations :simple
289
                    :pretty-print true
290
                    :source-map true
291
                    :target :nodejs}
292
 
293
 :closure-defines {goog.DEBUG false
294
                   myapp.config/API_URL "https://api.example.com"}
295
 
296
 :js-options {:resolve {"react" {:target :npm
297
                                :require "react"}}
298
              :packages {"lodash" {:entry-keys [:module :main]}}}}
299
```
300

301
### User Configuration
302

303
Personal settings that can be version-controlled separately.
304

305
```clojure { .api }
306
:user-config map
307
;; User-specific configuration options
308
;; Typically loaded from separate file or environment
309

310
;; Common user config options:
311
{:http-port number                   ;; Preferred development server port
312
 :nrepl-port number                 ;; Preferred nREPL port
313
 :open-browser boolean              ;; Auto-open browser on server start
314
 :supervisor boolean                ;; Enable build supervisor
315
 :build-notify boolean              ;; Desktop notifications for builds}
316
```
317

318
**Usage Examples:**
319

320
```clojure
321
;; User-specific preferences
322
{:user-config {:http-port 3000
323
               :nrepl-port 7888
324
               :open-browser true
325
               :build-notify false}}
326
```