0
# Shadow-CLJS
1

2
Shadow-CLJS is a comprehensive ClojureScript build tool and development environment that provides seamless npm integration, fast builds with reliable caching, and support for multiple deployment targets including browser, Node.js scripts, npm modules, React Native, and Chrome extensions. It offers live reload capabilities, an integrated REPL for interactive development, code splitting through modules, and good configuration defaults to minimize setup complexity.
3

4
## Package Information
5

6
- **Package Name**: shadow-cljs
7
- **Package Type**: npm
8
- **Language**: ClojureScript/JavaScript
9
- **Installation**: `npm install -g shadow-cljs`
10

11
## Core Imports
12

13
Shadow-CLJS is primarily used as a CLI tool:
14

15
```bash
16
shadow-cljs compile app
17
shadow-cljs watch app
18
```
19

20
For programmatic usage in Clojure code:
21

22
```clojure
23
(require '[shadow.cljs.devtools.api :as shadow])
24
```
25

26
## Basic Usage
27

28
### Project Setup
29

30
```bash
31
# Create a new shadow-cljs project
32
npx create-cljs-project my-project
33
cd my-project
34

35
# Install dependencies
36
npm install
37

38
# Watch and compile for development
39
shadow-cljs watch app
40

41
# Compile for production
42
shadow-cljs release app
43
```
44

45
### Configuration (shadow-cljs.edn)
46

47
```clojure
48
{:source-paths ["src"]
49
 :dependencies [[reagent "1.1.1"]]
50
 :builds {:app {:target :browser
51
                :output-dir "public/js"
52
                :asset-path "/js"
53
                :modules {:main {:init-fn my-app.core/init}}}}}
54
```
55

56
## Architecture
57

58
Shadow-CLJS is built around several key components:
59

60
- **CLI Interface**: Primary user interface providing commands for compilation, development server, and REPL
61
- **Build System**: Core compilation engine with support for multiple targets and optimization modes
62
- **Development Server**: Hot reload and asset serving with WebSocket communication
63
- **REPL Integration**: Interactive development with browser, Node.js, and build-specific REPLs
64
- **Configuration System**: Declarative build configuration through `shadow-cljs.edn`
65
- **Module System**: Code splitting and dependency management for large applications
66

67
## Capabilities
68

69
### CLI Commands
70

71
Primary command-line interface for building, watching, and development workflow management.
72

73
```bash { .api }
74
# Build commands
75
shadow-cljs compile <build-id>     # Compile once and exit
76
shadow-cljs watch <build-id>       # Watch for changes and recompile
77
shadow-cljs release <build-id>     # Compile with optimizations
78
shadow-cljs check <build-id>       # Check for compilation errors
79

80
# Development server
81
shadow-cljs server                 # Start development server
82
shadow-cljs start                  # Start development server
83
shadow-cljs stop                   # Stop development server
84
shadow-cljs restart                # Restart development server
85

86
# REPL commands  
87
shadow-cljs repl <build-id>        # Start build-specific REPL
88
shadow-cljs node-repl              # Start Node.js REPL
89
shadow-cljs browser-repl           # Start browser REPL
90

91
# Testing commands
92
shadow-cljs test                   # Run tests
93
shadow-cljs node-test <build-id>   # Run Node.js tests
94
shadow-cljs karma <build-id>       # Run browser tests
95
```
96

97
[CLI Commands](./cli-commands.md)
98

99
### Programmatic API
100

101
Core API functions for programmatic build control and automation.
102

103
```clojure { .api }
104
(require '[shadow.cljs.devtools.api :as shadow])
105

106
;; Compilation functions
107
(shadow/compile build-id)          ;; Compile build once
108
(shadow/watch build-id)            ;; Start watching build
109
(shadow/release build-id)          ;; Compile with optimizations
110
(shadow/check build-id)            ;; Check compilation errors
111

112
;; REPL functions
113
(shadow/repl build-id)             ;; Start build REPL
114
(shadow/node-repl)                 ;; Start Node.js REPL
115
(shadow/browser-repl)              ;; Start browser REPL
116

117
;; Runtime management
118
(shadow/get-runtime!)              ;; Get current runtime
119
(shadow/get-build-ids)             ;; List configured builds
120
(shadow/active-builds)             ;; List active builds
121

122
;; Watch management  
123
(shadow/watch-compile! build-id)   ;; Manual recompile
124
(shadow/watch-set-autobuild! build-id toggle) ;; Control autobuild
125

126
;; Dependency management
127
(shadow/reload-deps!)              ;; Reload dependencies
128
```
129

130
[Programmatic API](./programmatic-api.md)
131

132
### Build Configuration
133

134
Comprehensive build configuration system supporting multiple targets and deployment modes.
135

136
```clojure { .api }
137
;; shadow-cljs.edn structure
138
{:source-paths [string]            ;; Source directories
139
 :dependencies [dependency-vector] ;; ClojureScript dependencies
140
 :builds {build-id build-config}   ;; Build configurations
141
 :dev-http {port config}           ;; Development HTTP server
142
 :nrepl {port config}              ;; nREPL server settings}
143

144
;; Build target types
145
:browser                           ;; Browser applications
146
:node-script                       ;; Node.js scripts
147
:node-library                      ;; Node.js libraries
148
:npm-module                        ;; NPM publishable modules
149
:react-native                      ;; React Native applications
150
:chrome-extension                  ;; Chrome extensions
151
```
152

153
[Build Configuration](./build-configuration.md)
154

155
### Build Targets
156

157
Specialized build targets for different deployment environments and use cases.
158

159
```clojure { .api }
160
;; Browser target
161
{:target :browser
162
 :output-dir "public/js"
163
 :asset-path "/js" 
164
 :modules {:main {:init-fn app.core/init}}}
165

166
;; Node.js script target
167
{:target :node-script
168
 :main app.server/main
169
 :output-to "server.js"}
170

171
;; NPM module target
172
{:target :npm-module
173
 :entries [app.api]
174
 :output-dir "dist"}
175
```
176

177
[Build Targets](./build-targets.md)
178

179
## Types
180

181
```clojure { .api }
182
;; Build configuration map
183
BuildConfig {
184
  :target keyword                  ;; Build target type
185
  :output-dir string              ;; Output directory path
186
  :asset-path string              ;; Asset path for resources
187
  :modules map                    ;; Module configuration
188
  :dev map                        ;; Development options
189
  :release map                    ;; Release options
190
  :compiler-options map           ;; ClojureScript compiler options
191
}
192

193
;; Build state map
194
BuildState {
195
  :build-id keyword               ;; Build identifier
196
  :target keyword                 ;; Build target type
197
  :stage keyword                  ;; Current compilation stage
198
  :classpath vector               ;; Build classpath
199
  :sources map                    ;; Source files map
200
  :modules map                    ;; Module definitions
201
}
202

203
;; Runtime connection map
204
Runtime {
205
  :runtime-id string              ;; Runtime identifier
206
  :lang keyword                   ;; Runtime language (:cljs, :js)
207
  :build-id keyword               ;; Associated build
208
  :client-info map                ;; Client connection info
209
}
210
```