thheller / thheller/shadow-cljs
Expose shadow-remote endpoint over nREPL
Nobody has claimed this yet.
- Dominant language
- Clojure
- Stars
- 2.4k
- Forks
- 192
- Avg merge
- 3h 11m
- Merged PRs (30d)
- 1
Description
Most editors have a working nREPL implementation so it makes sense to tunnel shadow-remote over nREPL. As of 2.17.3 there are 3 new related nREPL ops to get full access to shadow-remote. If editors aren't interested in these they can just be ignored, all existing operations are unaffected.
The intent is that an editor that is interested sends a message once to initiate a "connection". The init message must contain a :data-type with either edn or transit. Depending on what is chosen there all following shadow-remote-msg messages are expected to have a :data string value encoded in the chosen type.
{:op "shadow-remote-init" :data-type "edn"}
;; or
{:op "shadow-remote-init" :data-type "transit"}
After the init the "connection" is open and the editor will start receiving messages from the shadow-remote relay. The editor may also send further messages by wrapping the actual message in a nREPL envelope.
;; messages from either the editor or the relay
{:op "shadow-remote-msg" :data "encoded string"}
Further details on shadow-remote can be found in this post. If any editor implementors have any interest in this I'll expand that document to include all currently available messages and their use. As of now it powers everything in the shadow-cljs UI as well as any existing REPL implementation. So even nREPL eval is already using it under the hood, just not exposed in fine detail.
Please reach out if you attempt to work on this on the editor side. Happy to help out with protocol questions.
A note on nREPL session management. The editor may clone a new session for this but all shadow-remote related messages must then use that session. If a shadow-remote-msg is received before shadow-remote-init it'll be rejected and just send an :err. I also don't know how any existing nREPL middleware may interfere with this.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading doc/remote.md and tracing the existing nREPL handling and shadow-remote relay entry points. Implement the shadow-remote-init and shadow-remote-msg operations with EDN or transit data, session consistency, and rejection before initialization; done means editors can exchange all specified messages through nREPL without affecting existing operations.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- clojure
- Domain
- api, developer-experience
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100