nREPL WebSocket Client

A proof-of-concept for using a browser to write, load and evaluate Clojure code running on a Websocket-connected nREPL server, processing the results for display using the Scicloj notebook library clay.

Features

• ClojureScript app using Reagent
• Structural editing and syntax highlighting courtesy of CodeMirror and clojure-mode
• Multiple evaluation modes :
  • REPL mode: Standard evaluation using text output
  • Clay mode: Notebook evaluation using indirect rendering inside an iframe
  • Clay Hiccup mode: As above but using direct rendering of Hiccup data in the Reagent interface. Note: this mode is still experimental, but it does support tabular output from Tablecloth and Plotly charts from Tableplot.
• Keyboard shortcuts for evaluation:
  • Alt+Enter: Evaluate editor content
  • Ctrl+Enter: Evaluate form at cursor
  • Ctrl+Shift+Enter: Evaluate top-level form at cursor

Prerequisites

• Node.js and npm
• Java 11 or later (tested with Java 21)
• Clojure CLI tools
• nREPL server with WebSocket support running at ws://localhost:7888.

Alternatively, use an editor or environment that supports dev containers. The supplied devcontainer.json will install all the above prerequisites.

Usage

This project and the Websocket nREPL server are expected to be used in a "hosted" fashion with zero end-user setup required. However, the steps required for self-hosting are provided here for completeness.

Clone the server repository :

cd /workspaces
git clone https://github.com/alza-bitz/nrepl-ws-server.git

Start the Websocket nREPL server in a separate terminal :

cd /workspaces/nrepl-ws-server
clojure -M:nrepl-ws

Clone the client repository :

cd /workspaces
git clone https://github.com/alza-bitz/nrepl-ws-client.git
cd nrepl-ws-client

Install the dependencies :

npm install

Start the shadow-cljs server :

clojure -M:shadow-cljs watch main

Finally, open your browser at http://localhost:8020

Development

Start the shadow-cljs server

clojure -M:shadow-cljs watch main

Running the tests

clojure -M:shadow-cljs:test compile test

Build for production

clojure -M:shadow-cljs release main

Examples

Client running the noj getting started tutorial in Clay mode :

Client running the noj getting started tutorial in Clay Hiccup mode :

License

Copyright © 2025 Alex Coyle

Distributed under the Eclipse Public License version 2.0.

See the LICENSE file for details.