Skip to content

Document non-browser runtime support #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bbatsov merged 1 commit into from
Jun 27, 2026
Merged

Document non-browser runtime support #81

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 24 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,10 @@ APIs.
standard ClojureScript browser REPL and Austin. (see:
[cemerick/austin#17][austin-17], [cemerick/austin#47][austin-47],
[cemerick/austin#49][austin-49])
* WebSocket APIs are available in unusual JavaScript environments like
[JavaScriptCore][goby], [QML][qml], [WinJS][winjs], browser
extensions, Mac OS X Dashboard widgets, and so on, where use of
`CrossPageChannel` may be unfeasible due to restrictions on or
unavailability of `<iframe>` elements. Weasel allows the
ClojureScript developer to still enjoy the benefits of REPL driven
development in these exotic domains.
* WebSocket APIs are available far beyond the browser - Node, Deno, Bun, web
and service workers, browser extensions, React Native, and more exotic
embeddings like [QML][qml] - so Weasel can give you a REPL driven workflow in
environments where the iframe-based standard browser REPL simply can't run.

## Usage

Expand Down Expand Up @@ -116,6 +113,25 @@ cljs.user> (do (js/alert "Hello world!") 42)
42
```

### Non-browser runtimes

Because the client talks over the platform's native `WebSocket`, it isn't tied
to the browser. Any runtime with a global `WebSocket` works, including Node 22+,
Deno, Bun, and web/service workers. Require `weasel.repl` from code compiled for
that target and call `repl/connect` exactly as you would in a browser:

```clojure
(ns my.app
(:require [weasel.repl :as repl]))

(repl/connect "ws://localhost:9001")
```

The only browser-specific piece is Closure's script-tag code loading used to
pull in namespaces first required at the REPL; it's skipped automatically when
there is no `document`. Evaluating forms, printing, reconnection and the
heartbeat all behave the same everywhere.

Note that unless a client is connected to the WebSocket channel,
evaluation will fail:

Expand All @@ -137,17 +153,15 @@ this project.
## Need help?

If you have any feedback or issues to report, feel free to open an
issue on [GitHub](https://github.com/tomjakubowski/weasel).
issue on [GitHub](https://github.com/nrepl/weasel).

## A weasel "piggiebacking" on a woodpecker

A little treat for reading the whole README!

![](http://i.imgur.com/XIaZZ2k.jpg)

[goby]: <https://github.com/mfikes/goby>
[qml]: <http://doc.qt.io/qt-5/qml-qt-websockets-websocket.html>
[winjs]: <https://msdn.microsoft.com/en-us/library/windows/apps/hh761442.aspx>
[nREPL]: <https://github.com/nrepl/nrepl>
[piggieback]: <https://github.com/nrepl/piggieback>
[austin-17]: <https://github.com/cemerick/austin/issues/17>
Expand Down
Loading