CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-shadow-cljs

ClojureScript compiler and JS bundler with comprehensive development tooling

—

Pending
Overview
Eval results
Files

build-configuration.mddocs/

Build Configuration

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.

Configuration File Structure

shadow-cljs.edn

The primary configuration file located in the project root.

{:source-paths [string]              ;; Vector of source directory paths
 :resource-paths [string]            ;; Vector of resource directory paths  
 :dependencies [dependency-vector]   ;; ClojureScript dependencies
 :dev-dependencies [dependency-vector] ;; Development-only dependencies
 :builds {build-id build-config}     ;; Map of build configurations
 :dev-http {port config}             ;; Development HTTP server settings
 :nrepl {:port number :host string}  ;; nREPL server configuration
 :socket-repl {:port number :host string} ;; Socket REPL configuration
 :deps true                          ;; Enable deps.edn integration
 :user-config map                    ;; User-specific configuration
 :closure-defines map                ;; Global closure defines
 :compiler-options map               ;; Global compiler options
 :js-options map                     ;; JavaScript processing options}

Usage Example:

{:source-paths ["src/main" "src/shared"]
 :resource-paths ["resources"]
 :dependencies [[reagent "1.1.1"]
                [re-frame "1.2.0"]]
 :dev-dependencies [[binaryage/devtools "1.0.4"]]
 
 :builds
 {:app {:target :browser
        :output-dir "public/js"
        :asset-path "/js"
        :modules {:main {:init-fn myapp.core/init
                        :preloads [devtools.preload]}}}
  
  :test {:target :node-test
         :output-to "out/test.js"
         :autorun true}}
 
 :dev-http {8080 "public"
            9000 {:root "resources/public"
                  :push-state/index "index.html"}}
 
 :nrepl {:port 8777}}

Capabilities

Source Path Configuration

Defines where Shadow-CLJS looks for ClojureScript source files.

:source-paths [string]
;; Vector of directory paths containing .cljs, .cljc, and .clj files
;; Paths are relative to project root
;; Default: ["src"]

:resource-paths [string]  
;; Vector of directory paths containing static resources
;; Resources are available on classpath
;; Default: ["resources"]

Usage Examples:

;; Basic source configuration
{:source-paths ["src"]}

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

;; Source and resource paths
{:source-paths ["src"]
 :resource-paths ["resources" "assets"]}

Dependency Configuration

Manages ClojureScript and Clojure dependencies for the project.

:dependencies [dependency-vector]
;; Vector of dependency specifications [lib-name version & options]
;; lib-name: symbol representing library name
;; version: string version specification
;; options: optional map with :exclusions, :scope, etc.

:dev-dependencies [dependency-vector]
;; Dependencies only loaded during development
;; Not included in production builds
;; Same format as :dependencies

Usage Examples:

;; Basic dependencies
{:dependencies [[org.clojure/clojurescript "1.11.54"]
                [reagent "1.1.1"]
                [re-frame "1.2.0"]]}

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

;; Development dependencies
{:dev-dependencies [[binaryage/devtools "1.0.4"]
                    [day8.re-frame/re-frame-10x "1.2.2"]]}

Build Configuration

Core build settings that define how ClojureScript code is compiled.

:builds {build-id build-config}
;; Map where keys are build identifiers (keywords)
;; Values are build configuration maps

;; Build configuration structure:
{:target keyword                     ;; Build target type
 :output-dir string                  ;; Output directory path
 :output-to string                   ;; Single output file path (some targets)
 :asset-path string                  ;; Public path for generated assets
 :public-dir string                  ;; Public directory for assets
 :modules map                        ;; Module configuration for code splitting
 :entries [namespace-symbol]         ;; Entry point namespaces
 :main namespace-symbol              ;; Main namespace (some targets)
 :init-fn symbol                     ;; Initialization function
 :dev map                           ;; Development-specific options
 :release map                       ;; Release/production options
 :compiler-options map              ;; ClojureScript compiler options
 :js-options map                    ;; JavaScript processing options
 :closure-defines map               ;; Closure compiler defines
 :devtools map                      ;; Development tools configuration}

Usage Examples:

;; Browser application build
{:builds
 {:app {:target :browser
        :output-dir "public/js"
        :asset-path "/js"
        :modules {:main {:init-fn myapp.core/init
                        :depends-on #{:shared}}
                  :shared {:entries [myapp.util]}}
        :dev {:preloads [devtools.preload]
              :console-support true}
        :release {:module-hash-names true
                  :optimize-constants true}}}}

;; Node.js script build  
{:builds
 {:server {:target :node-script
           :main myapp.server/main
           :output-to "server.js"
           :devtools {:enabled false}}}}

Development Server Configuration

HTTP server settings for serving static files and development assets.

:dev-http {port config}
;; Map where keys are port numbers
;; Values are either strings (root directory) or configuration maps

;; Server configuration options:
{:root string                        ;; Root directory to serve
 :push-state/index string           ;; SPA index file for pushState routing
 :push-state/headers map            ;; Additional headers for pushState responses
 :ssl-port number                   ;; HTTPS port
 :ssl-cert string                   ;; SSL certificate file path
 :ssl-key string                    ;; SSL key file path
 :handler symbol                    ;; Custom Ring handler function
 :middleware [symbol]               ;; Ring middleware functions
 :proxy-url string                  ;; Proxy backend URL
 :proxy-exclude-patterns [string]   ;; Paths to exclude from proxying}

Usage Examples:

;; Simple static file server
{:dev-http {8080 "public"}}

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

;; SSL configuration
{:dev-http {8080 "public"
            8443 {:root "public"
                  :ssl-cert "cert.pem"
                  :ssl-key "key.pem"}}}

;; Proxy configuration for API backend
{:dev-http {3000 {:root "public"
                  :proxy-url "http://localhost:8080"
                  :proxy-exclude-patterns ["/api"]}}}

REPL Configuration

Settings for interactive development environments.

:nrepl {:port number                 ;; nREPL server port
        :host string                 ;; nREPL server host
        :middleware [symbol]         ;; Additional nREPL middleware
        :init-ns symbol             ;; Initial namespace for REPL session}

:socket-repl {:port number           ;; Socket REPL port  
              :host string           ;; Socket REPL host
              :accept symbol         ;; Accept function symbol}

Usage Examples:

;; Basic nREPL configuration
{:nrepl {:port 8777}}

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

;; Socket REPL configuration
{:socket-repl {:port 8888
               :accept cljs.server.node/repl}}

Global Compiler Options

ClojureScript compiler settings applied to all builds.

:compiler-options map
;; Global ClojureScript compiler options
;; Individual builds can override these settings

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

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

:js-options map  
;; JavaScript processing options
{:resolve map                       ;; Module resolution configuration
 :packages map                      ;; Package-specific settings
 :entry-keys [keyword]              ;; Package.json entry point keys}

Usage Examples:

;; Global compiler options
{:compiler-options {:optimizations :simple
                    :pretty-print true
                    :source-map true
                    :target :nodejs}
 
 :closure-defines {goog.DEBUG false
                   myapp.config/API_URL "https://api.example.com"}
 
 :js-options {:resolve {"react" {:target :npm
                                :require "react"}}
              :packages {"lodash" {:entry-keys [:module :main]}}}}

User Configuration

Personal settings that can be version-controlled separately.

:user-config map
;; User-specific configuration options
;; Typically loaded from separate file or environment

;; Common user config options:
{:http-port number                   ;; Preferred development server port
 :nrepl-port number                 ;; Preferred nREPL port
 :open-browser boolean              ;; Auto-open browser on server start
 :supervisor boolean                ;; Enable build supervisor
 :build-notify boolean              ;; Desktop notifications for builds}

Usage Examples:

;; User-specific preferences
{:user-config {:http-port 3000
               :nrepl-port 7888
               :open-browser true
               :build-notify false}}

Install with Tessl CLI

npx tessl i tessl/npm-shadow-cljs

docs

build-configuration.md

build-targets.md

cli-commands.md

index.md

programmatic-api.md

tile.json