or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-configuration.mdbuild-targets.mdcli-commands.mdindex.mdprogrammatic-api.md
tile.json

tessl/npm-shadow-cljs

ClojureScript compiler and JS bundler with comprehensive development tooling

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/shadow-cljs@3.2.x

To install, run

npx @tessl/cli install tessl/npm-shadow-cljs@3.2.0

index.mddocs/

Shadow-CLJS

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.

Package Information

  • Package Name: shadow-cljs
  • Package Type: npm
  • Language: ClojureScript/JavaScript
  • Installation: npm install -g shadow-cljs

Core Imports

Shadow-CLJS is primarily used as a CLI tool:

shadow-cljs compile app
shadow-cljs watch app

For programmatic usage in Clojure code:

(require '[shadow.cljs.devtools.api :as shadow])

Basic Usage

Project Setup

# Create a new shadow-cljs project
npx create-cljs-project my-project
cd my-project

# Install dependencies
npm install

# Watch and compile for development
shadow-cljs watch app

# Compile for production
shadow-cljs release app

Configuration (shadow-cljs.edn)

{:source-paths ["src"]
 :dependencies [[reagent "1.1.1"]]
 :builds {:app {:target :browser
                :output-dir "public/js"
                :asset-path "/js"
                :modules {:main {:init-fn my-app.core/init}}}}}

Architecture

Shadow-CLJS is built around several key components:

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

Capabilities

CLI Commands

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

# Build commands
shadow-cljs compile <build-id>     # Compile once and exit
shadow-cljs watch <build-id>       # Watch for changes and recompile
shadow-cljs release <build-id>     # Compile with optimizations
shadow-cljs check <build-id>       # Check for compilation errors

# Development server
shadow-cljs server                 # Start development server
shadow-cljs start                  # Start development server
shadow-cljs stop                   # Stop development server
shadow-cljs restart                # Restart development server

# REPL commands  
shadow-cljs repl <build-id>        # Start build-specific REPL
shadow-cljs node-repl              # Start Node.js REPL
shadow-cljs browser-repl           # Start browser REPL

# Testing commands
shadow-cljs test                   # Run tests
shadow-cljs node-test <build-id>   # Run Node.js tests
shadow-cljs karma <build-id>       # Run browser tests

CLI Commands

Programmatic API

Core API functions for programmatic build control and automation.

(require '[shadow.cljs.devtools.api :as shadow])

;; Compilation functions
(shadow/compile build-id)          ;; Compile build once
(shadow/watch build-id)            ;; Start watching build
(shadow/release build-id)          ;; Compile with optimizations
(shadow/check build-id)            ;; Check compilation errors

;; REPL functions
(shadow/repl build-id)             ;; Start build REPL
(shadow/node-repl)                 ;; Start Node.js REPL
(shadow/browser-repl)              ;; Start browser REPL

;; Runtime management
(shadow/get-runtime!)              ;; Get current runtime
(shadow/get-build-ids)             ;; List configured builds
(shadow/active-builds)             ;; List active builds

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

;; Dependency management
(shadow/reload-deps!)              ;; Reload dependencies

Programmatic API

Build Configuration

Comprehensive build configuration system supporting multiple targets and deployment modes.

;; shadow-cljs.edn structure
{:source-paths [string]            ;; Source directories
 :dependencies [dependency-vector] ;; ClojureScript dependencies
 :builds {build-id build-config}   ;; Build configurations
 :dev-http {port config}           ;; Development HTTP server
 :nrepl {port config}              ;; nREPL server settings}

;; Build target types
:browser                           ;; Browser applications
:node-script                       ;; Node.js scripts
:node-library                      ;; Node.js libraries
:npm-module                        ;; NPM publishable modules
:react-native                      ;; React Native applications
:chrome-extension                  ;; Chrome extensions

Build Configuration

Build Targets

Specialized build targets for different deployment environments and use cases.

;; Browser target
{:target :browser
 :output-dir "public/js"
 :asset-path "/js" 
 :modules {:main {:init-fn app.core/init}}}

;; Node.js script target
{:target :node-script
 :main app.server/main
 :output-to "server.js"}

;; NPM module target
{:target :npm-module
 :entries [app.api]
 :output-dir "dist"}

Build Targets

Types

;; Build configuration map
BuildConfig {
  :target keyword                  ;; Build target type
  :output-dir string              ;; Output directory path
  :asset-path string              ;; Asset path for resources
  :modules map                    ;; Module configuration
  :dev map                        ;; Development options
  :release map                    ;; Release options
  :compiler-options map           ;; ClojureScript compiler options
}

;; Build state map
BuildState {
  :build-id keyword               ;; Build identifier
  :target keyword                 ;; Build target type
  :stage keyword                  ;; Current compilation stage
  :classpath vector               ;; Build classpath
  :sources map                    ;; Source files map
  :modules map                    ;; Module definitions
}

;; Runtime connection map
Runtime {
  :runtime-id string              ;; Runtime identifier
  :lang keyword                   ;; Runtime language (:cljs, :js)
  :build-id keyword               ;; Associated build
  :client-info map                ;; Client connection info
}