Refine shadow-cljs documentation (#3360)

Author: vemv

doc/modules/ROOT/pages/basics/middleware_setup.adoc

@@ -89,7 +89,7 @@ run `cider-connect` or `cider-connect-cljs`.
 
   :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"}
                             cider/cider-nrepl {:mvn/version "0.22.4"}
-                            cider/piggieback {:mvn/version "0.5.1"}}
+                            cider/piggieback {:mvn/version "0.5.3"}}
                :main-opts ["-m" "nrepl.cmdline" "--middleware"
                            "[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}
 ----

doc/modules/ROOT/pages/cljs/figwheel.adoc

@@ -25,7 +25,7 @@ You'll also have to configure Piggieback manually if you're planning to use
 +
 [source,clojure]
 ----
-[cider/piggieback "0.5.1"]
+[cider/piggieback "0.5.3"]
 ----
 +
 . Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
@@ -123,7 +123,7 @@ in the root of your Leiningen project definition.
 +
 [source,clojure]
 ----
-[cider/piggieback "0.5.1"] ; not needed for cider-jack-in-cljs
+[cider/piggieback "0.5.3"] ; not needed for cider-jack-in-cljs
 [figwheel-sidecar "0.5.19"] ; use here whatever the current version of figwheel is
 ----
 +

doc/modules/ROOT/pages/cljs/other_repls.adoc

@@ -61,7 +61,7 @@ Internally, it's powered by Weasel. Let's go over the steps required to use it.
 [adzerk/boot-cljs-repl   "X.Y.Z"  :scope "test"]
 [pandeiro/boot-http      "X.Y.Z"  :scope "test"]
 [weasel                  "0.7.1"  :scope "test"]
-[cider/piggieback "0.5.1"  :scope "test"] ; not needed for cider-jack-in-cljs
+[cider/piggieback "0.5.3"  :scope "test"] ; not needed for cider-jack-in-cljs
 ----
 +
 and this at the end of `build.boot`:

doc/modules/ROOT/pages/cljs/overview.adoc

@@ -17,7 +17,7 @@ and how to setup the most popular ClojureScript REPLs.
 == nREPL and ClojureScript
 
 nREPL doesn't natively support ClojureScript evaluation, that why an additional
-middleware is needed. CIDER relies on the popular Piggieback middleware for its
+middleware is needed. For most REPLs (with the notable exceptions of `shadow-cljs`, `nbb`), CIDER relies on the popular Piggieback middleware for its
 ClojureScript support.
 
 Piggieback works in the following manner:
@@ -32,7 +32,9 @@ On the bright side - this also means that you can host side by side Clojure and
 REPLs in a single nREPL connection! This opens up all sorts of interesting possibilities
 that we'll discuss later on.
 
-== Differences with the Standard ClojureScript REPL
+NOTE: `shadow-cljs`'s REPL is implemented in a very similar fashion, but its mechanism is provided by its own nREPL middleware - not Piggieback.
+
+== Piggieback differences with the Standard ClojureScript REPL
 
 While the Piggieback-powered ClojureScript REPLs behave more or less
 the same as the standard ClojureScript REPL, there are few subtle

doc/modules/ROOT/pages/cljs/shadow-cljs.adoc

@@ -54,15 +54,26 @@ Alternatively you can start the server manually with something like:
 
 [source,sh]
 ----
-$ npx shadow-cljs server
+$ shadow-cljs watch app
 ----
 
 And connect to it with `cider-connect`.
 
+...For that to work, `shadow-cljs.edn` contents like the following are assumed:
+
+```clj
+ :dependencies [[cider/cider-nrepl "0.31.0"] ;; mandatory (unless it's inherited from deps.edn or otherwise present in the classpath of shadow-cljs's JVM process)
+                [refactor-nrepl/refactor-nrepl "3.6.0"]] ;; refactor-nrepl is optional
+
+ :nrepl {:middleware [cider.nrepl/cider-middleware ;; it's advisable to explicitly add this middleware. It's automatically added by shadow-cljs (if available in the classpath), unless `:nrepl {:cider false}`
+                      refactor-nrepl.middleware/wrap-refactor] ;; refactor-nrepl is optional
+         :port 50655} ;; optional - if not specified, a random free port will be used
+```
+
 NOTE: If https://docs.cider.mx/cider-nrepl/[cider-nrepl] isn't in your
-classpath you should make sure it's there. You can do this by adding
-it to `:dependencies` in the `shadow-cljs.edn` configuration file
-residing in the root of your project. Alternatively you can set
+classpath you should make sure it's there. You can do this by correctly filling
+the `shadow-cljs.edn` configuration file
+residing in the root of your project, as described above. Alternatively you can set
 `cider-repl-auto-detect-type` to `nil`, as the auto-detection of
 REPL types doesn't work without `cider-nrepl`.
 
@@ -139,7 +150,3 @@ Here are a few useful sections from ``shadow-cljs``'s own documentation:
 * https://shadow-cljs.github.io/docs/UsersGuide.html#_installation[Installation]
 * https://shadow-cljs.github.io/docs/UsersGuide.html#nREPL[nREPL Setup]
 * https://shadow-cljs.github.io/docs/UsersGuide.html#cider[Integration with CIDER]
-
-=== Tutorials
-
-* https://cestlaz.github.io/post/using-emacs-63-clojurescript/[Using shadow-cljs with CIDER]

doc/modules/ROOT/pages/cljs/up_and_running.adoc

@@ -25,7 +25,7 @@ project or `deps.edn`):
 [source,clojure]
 ----
 ;; use whatever are the most recent versions here
-[cider/piggieback "0.5.1"]
+[cider/piggieback "0.5.3"]
 [org.clojure/clojure "1.9.0"]
 ----