shadow-cljs

Overview

shadow.remote is a new architecture designed to provide a generic, runtime-agnostic alternative to nREPL for ClojureScript. It addresses limitations in existing REPL tools, such as the "Print Problem" (handling extremely large or unprintable values) and the difficulty of running REPL UIs in non-JVM runtimes like browsers, React Native, or Node.js.

Core Components

• Relay: A central hub (implemented in CLJ) that handles message routing between clients. A relay is required because certain runtimes (like browsers) cannot accept direct incoming connections and must instead connect to a relay. The relay manages client lifecycles and forwards messages based on routing numbers.
• Client: Any runtime or tool participating in the protocol. Clients are passive by default and initiate actions. Clients can be runtimes (e.g., a browser app) or tools (e.g., a UI debugger). Clients use :client-info to discover one another via the relay.

In the context of ClojureScript, it is important to distinguish between the ClosureJS module format and ESM (ECMAScript Modules):

ClosureJS (The traditional CLJS format)

• Mechanism: Uses an ad-hoc namespacing system via goog.provide. It creates nested objects in the global scope (e.g., goog.provide("cljs.core") creates var cljs = { core: {} };).
• Pros: The shared global scope makes implementing REPLs and Hot Module Replacement (HMR) trivial, as you can redeclare variables at runtime. It also allows easy inspection of state via browser devtools.
• Cons: It is not a web standard, making interop with the broader JavaScript ecosystem difficult and requiring "glue code" or global hacks. It also requires a "Debug Loader" to manage dependency ordering in unoptimized builds.

ESM (The modern JS standard)

• Mechanism: Each module has its own private scope. Variables are not shared unless explicitly exported and imported.
• Pros: It is the industry standard, supported by all modern browsers and runtimes, allowing for seamless interop with regular JavaScript.
• Cons: Because modules have private scopes, you cannot easily modify or inspect state from the outside. In ClojureScript, strict ESM makes features like the REPL and dynamic HMR more complex because you cannot easily add exports or redeclare bindings after a module has been loaded.

While you can publish CLJS libraries to npm using :npm-module or :esm, doing so for multiple packages introduces significant issues:

• Duplicate Core Libraries: Each package will bundle its own cljs.core, leading to incompatible data structures (e.g., different implementations of {} or []) and large artifact sizes.
• Macro Support: Compiled JS code cannot consume CLJS macros. The CLJS compiler requires a local version of the source to access macros and analyzer data.
• Optimization Loss: Publishing modularly as separate npm packages makes it difficult to utilize :advanced optimizations, which are necessary for effective dead-code elimination.

To incrementally introduce CLJS into an existing JS project, it is recommended to use existing :npm-module or :esm capabilities within a single build context rather than attempting to manage multiple independent CLJS-to-npm packages.

The :target :esm option allows you to emit ES Module (ESM) import/export statements instead of CommonJS. This target is designed to reduce boilerplate and work well with code-splitting :modules.

Key Characteristics:

• Exports: Instead of providing every namespace as an individual artifact, it uses a configurable :exports option to map CLJS fully qualified names to regular ESM export names.
• Development Mode: Unoptimized output uses globalThis to expose globals (like cljs), enabling features like hot-reload and REPL. This works in environments like browsers, Node.js, and Deno.
• Production Mode: Optimized code does not expose globals and does not rely on globalThis, making it compatible with all ESM-compliant systems.
• Runtime Loading: Because it integrates with standard ESM, you can instruct the runtime (e.g., a browser) to load dependencies directly rather than bundling them with shadow-cljs.

The Object Flow allows a client to incrementally query information or different "views" of an object using an :oid (Object ID).

Describing an Object

To get a summary of an object:

{:op :obj-describe :to id :oid oid}

;; Success response
{:op :opj-summary :oid oid :summary {...}}

;; Not found response
{:op :opj-not-found :oid oid}

Requesting Specific Views

Once you have a summary, you can request specific representations (like EDN, string, or pprint) using :request-op:

{:op :obj-request :to id :oid oid :request-op :edn}
{:op :obj-request :to id :oid oid :request-op :str}
{:op :obj-request :to id :oid oid :request-op :pprint}

;; Success response
{:op :obj-result :from id :result <request-op-return-value>}

;; Error responses
{:op :obj-not-found :from id :oid oid}
{:op :obj-request-not-supported :oid oid :request-op kw}
{:op :obj-request-failed :oid oid :ex-oid ex-oid :msg msg}