shadow-cljs-user-guide

可以一次性 compile 一个开发构建, 或者运行一个 watch 进程, 该进程将监视源文件并自动重新编译它们 (如果需要, 还可以实时重载代码).

所有开发构建都为开发者体验进行了优化, 具有快速的反馈周期和其他功能, 如 REPL, 可以直接与你正在运行的代码进行交互.

开发构建不应该公开发布, 因为它们可能会变得非常大, 并且可能仅在编译它们的机器上工作, 具体取决于 :target.

创建一个 release 构建将剥离所有与开发相关的代码, 并最终通过 Closure Compiler 运行代码. 这是一个针对 JavaScript 的优化编译器, 它将显著减小代码的整体大小.

shadow-cljs 使用 Java 虚拟机 (JVM) 及其 "classpath" 来处理文件. 这是一个由许多 classpath 条目组成的虚拟文件系统. 每个条目要么是

• 一个本地文件系统目录, 由配置中的 :source-paths 条目管理.
• 或者一个 .jar 文件, 代表 Clojure(Script) 或 JVM 库. 它们是包含许多文件的压缩存档 (基本上就是一个 .zip 文件). 这些是由你的 :dependencies 添加的.

在 Clojure(Script) 中, 所有东西都是有命名空间的, 每个名称都期望解析为一个文件. 如果你有一个 (ns demo.app) 命名空间, 编译器期望在 classpath 上找到一个 demo/app.cljs (或 .cljc). classpath 将按顺序搜索, 直到找到为止. 假设你配置了 :source-paths ["src/main" "src/test"], 编译器将首先查找 src/main/demo/app.cljs, 然后是 src/test/demo/app.cljs. 当在任何源路径上都找不到文件时, JVM 将开始在 classpath 上的 .jar 文件中查找. 当它在任何库的根目录下找到 demo/app.cljs 时, 该文件将被使用.

当一个文件名在 classpath 上多次存在时, 只使用第一个. JVM 和 Clojure(Script) 上的所有东西都是有命名空间的, 以避免此类冲突. 这与 npm 非常相似, 每个包都必须有一个唯一的名称.

因此, 建议在选择名称和正确命名所有东西方面非常严谨. 总是使用 (ns your-company.components.foo) 而不是 (ns components.foo) 可能看起来很重复, 但它会在以后为你省去很多麻烦.

这与 npm 不同, npm 包名本身从不用于包内部, 只使用相对路径.

shadow-cljs 可以以 "服务器" 模式启动, 这对于像 watch 这样的长时间运行的任务是必需的. watch 会隐式地启动服务器实例 (如果它尚未运行). 服务器将提供构建将连接到的 Websocket 端点, 以及用于 nREPL, Socket REPL 和开发 HTTP 服务器的所有其他端点.

当使用 shadow-cljs CLI 时, 所有命令都将重用正在运行的服务器实例 JVM, 而不是启动一个新的 JVM. 这要快得多, 因为启动时间可能相当慢.

然而, 一旦服务器运行起来, 只需在 :dependencies 更改时重新启动它, 其他所有事情都可以通过 REPL 完成.

REPL 是所有 Clojure(Script) 开发的核心, 每个 CLI 命令也可以直接从 REPL 使用. 即使命令行看起来更熟悉, 也绝对值得去适应 REPL.

这是一项正在进行中的工作. 如果你发现错误, 请提交 PR 来修复它, 或者提交一个 issue, 详细说明问题.

本书的源文件托管在 Github (https://github.com/shadow-cljs/shadow-cljs.github.io) 上.

本书中有许多示例. 其中使用的大多数东西从上下文中应该很明显, 但为了防止误解, 了解作者的意图很重要.

当给出命令行示例时, 我们可能会包含 BASH 注释 (以 # 开头), 并且通常会包含标准用户 UNIX 提示符 $ 来表示命令与其输出的分隔.

# 一个注释. 这个命令列出文件:
$ ls -l
shadow-cljs.edn
project.clj
...

许多示例是关于编译器的配置文件. 这个文件包含一个 EDN 映射. 在我们已经讨论过必需选项的地方, 我们通常会为了清晰而省略它们. 在这种情况下, 我们通常会包含一个省略号来表示 "必需但不是我们当前关注点的内容":

例 1. 指定依赖项

{:dependencies [[lib "1.0"]]}

例 2. 添加源路径

{...
 :source-paths ["src"]
 ...}

这使我们能够简洁地包含足够的上下文, 以理解感兴趣的配置的嵌套结构:

例 3. 嵌套选项

{...
 :builds {:build-id {...
                     :output-dir "resources/public/js"}}}

代码示例可能也会类似地缩短.

shadow-cljs 命令启动可能相当慢. 为了改善这一点, shadow-cljs 可以在 "服务器模式" 下运行, 这意味着启动一个专用进程, 所有其他命令都可以使用该进程来更快地执行, 因为它们不必启动新的 JVM/Clojure 实例.

执行长时间运行任务的命令 (例如 watch) 会隐式启动一个服务器实例, 但通常建议运行一个专用的服务器进程.

你可以在一个专用的终端中在前台运行该进程. 使用 CTRL+C 来终止服务器.

$ shadow-cljs server

# 或者 (如果你想用 REPL 来控制服务器进程)
$ shadow-cljs clj-repl

你也可以通过通用的 start|stop|restart 函数在后台运行服务器.

$ shadow-cljs start
$ shadow-cljs stop
$ shadow-cljs restart

一旦有任何服务器在运行, 其他所有命令都会使用它并运行得更快.

如果你想使用 Leiningen (https://leiningen.org/) 来管理你的依赖关系, 你可以通过在你的 shadow-cljs.edn 配置中添加一个 :lein 条目来实现. 有了这个设置, shadow-cljs 命令将使用 lein 来启动 JVM, 忽略 shadow-cljs.edn 中的任何 :source-paths 和 :dependencies; 而是依赖 lein 从 project.clj 中设置它们.

{:lein true
 ;; :source-paths 和 :dependencies 现在在此文件中被忽略
 ;; 通过 project.clj 配置它们
 :builds { ... }}

使用一个专用的 lein profile

{:lein {:profile "+cljs"}
 :builds {...}}

示例 project.clj

(defproject my-awesome-project
  ...
  :profiles
  {:cljs
   {:source-paths ["src/cljs"]
    :dependencies [[thheller/shadow-cljs "..."]
                   [reagent "0.8.1"]]}})

当使用 project.clj 管理你的 :dependencies 时, 你必须在你的 :dependencies 中 (直接或在一个 profile 中) 手动包含 thheller/shadow-cljs (https://clojars.org/thheller/shadow-cljs) 工件.

当启动 shadow-cljs 或尝试编译构建时遇到奇怪的 Java Stackstraces, 你可能遇到了依赖冲突. shadow-cljs 与特定匹配的 org.clojure/clojurescript 和 closure-compiler 版本一起使用非常重要. 你可以通过 lein deps :tree 检查, 所需版本列在 clojars (https://clojars.org/thheller/shadow-cljs) (在右侧) 上.

直接从 Leiningen 运行任务

如果你不想使用 shadow-cljs 命令本身, 你也可以直接通过 lein 执行 shadow-cljs 命令.

建议仍然使用 shadow-cljs 命令来运行命令, 因为这将充分利用正在运行的服务器模式实例. 当直接使用 lein 时, 这将比启动额外的 JVM 快得多.

只编译一次 :dev 模式, 无 REPL 或实时重载:

$ lein run -m shadow.cljs.devtools.cli compile build-id

创建一个 :release 模式的优化构建:

$ lein run -m shadow.cljs.devtools.cli release build-id

新的 deps.edn (https://clojure.org/guides/deps_and_cli) 也可以用来管理你的 :dependencies 和 :source-paths, 而不是使用内置方法或 lein. 所有 shadow-cljs 命令都将通过新的 clojure 实用程序启动.

tools.deps 仍在频繁变化. 请确保你使用的是最新版本.

要使用此功能, 请在你的配置中设置 :deps true 属性. 也可以配置应该使用哪些 deps.edn 别名.

你必须手动将 thheller/shadow-cljs 工件添加到你的 deps.edn 中.

简单的 shadow-cljs.edn 示例

{:deps true
 :builds ...}

简单的 deps.edn 示例

{:paths [...]
 :deps {thheller/shadow-cljs {:mvn/version <latest>}}}

带 :cljs 别名的 shadow-cljs.edn 示例

{:deps {:aliases [:cljs]}
 :builds ...}

示例 deps.edn

{:paths [...]
 :deps {...}
 :aliases
 {:cljs
  {:extra-deps {thheller/shadow-cljs {:mvn/version <latest>}}}}}

这样你就设置好了, 可以像平常一样运行 shadow-cljs.

选项: 直接通过 clj 运行

或者, 如果你想跳过直接运行 shadow-cljs 命令行工具, 你也可以直接通过 clj 运行.

这将绕过 "服务器模式". 这意味着你运行的任何东西都将运行一个新的 JVM 实例, 并且可能会慢得多. 你将失去一些在此处概述的功能 (https://code.thheller.com/blog/shadow-cljs/2017/11/18/the-many-ways-to-use-shadow-cljs.html). 除此之外, 编译结果将是相同的.

{:paths [...]
 :deps {...}
 :aliases
 {:shadow-cljs
  {:extra-deps {thheller/shadow-cljs {:mvn/version <latest>}}
   :main-opts ["-m" "shadow.cljs.devtools.cli"]}}}

clj -M:shadow-cljs watch app

你也可以通过命令行使用 -M 指定额外的别名, 例如 shadow-cljs -M:foo:bar ....

作者们对 Boot 的经验很少, 所以这一章需要贡献. 我们了解到 Boot 允许你用函数构建你的工具链. 由于 shadow-cljs 是一个普通的 JVM 库, 你可以调用其中的函数来调用任务.

一些 boot 任务可以在这里找到: https://github.com/jgdavey/boot-shadow-cljs

默认情况下, 由 clj-run 调用的函数只能访问一个最小的 shadow-cljs 运行时, 这足以运行 compile, release 和任何其他 Clojure 功能. 当你的函数完成时, JVM 将终止.

如果你想为给定的构建启动一个 watch, 你需要声明你正在调用的函数需要一个完整的服务器. 这将导致进程保持活动状态, 直到你显式调用 (shadow.cljs.devtools.server/stop!) 或按 CTRL+C 终止进程.

(ns demo.run
  (:require [shadow.cljs.devtools.api :as shadow]))

;; 这会失败, 因为缺少一个完整的服务器实例
(defn foo
  [& args]
  (shadow/watch :my-build))

;; 这个元数据将确保服务器被启动, 所以 watch 可以工作
(defn foo
  {:shadow/requires-server true}
  [& args]
  (shadow/watch :my-build))

$ shadow-cljs node-repl

这将启动一个带有已连接的 node 进程的空白 CLJS REPL.

如果你退出 Node REPL, node 进程也会被杀死!

node-repl 让你无需任何额外配置即可开始. 它可以通过通常的方式访问你的所有代码, 即 (require '[your.core :as x]). 由于它没有连接到任何构建, 当你的文件更改时, 它不会自动重新构建代码, 也不提供热重载.

$ shadow-cljs browser-repl

这将启动一个空白的 CLJS REPL, 并将打开一个关联的浏览器窗口, 代码将在其中执行. 除了在浏览器中运行外, 它具有与上述 node-repl 相同的所有功能.

如果你关闭浏览器窗口, REPL 将停止工作.

node-repl 和 browser-repl 在没有任何特定构建配置的情况下工作. 这意味着它们只会做你告诉它们做的事情, 而不会自己做任何事情.

如果你想构建一个特定的东西, 你应该使用提供的构建目标之一来配置一个构建. 它们中的大多数会自动注入 ClojureScript REPL 所需的代码. 它不应该需要任何额外的配置. 为了让构建的 CLJS REPL 工作, 你需要两件事:

1. 为你的构建运行一个 watch.
2. 连接 :target 的 JS 运行时. 这意味着如果你使用的是 :browser 目标, 你需要打开一个加载了生成的 JS 的浏览器. 对于 node.js 构建, 这意味着运行 node 进程.

一旦你两者都有了, 你就可以通过命令行或从 Clojure REPL 连接到 CLJS REPL.

CLI

$ shadow-cljs watch build-id
...
# 不同的终端
$ shadow-cljs cljs-repl build-id
shadow-cljs - connected to server
[3:1]~cljs.user=>

REPL

$ shadow-cljs clj-repl
...
[2:0]~shadow.user=> (shadow/watch :browser)
[:browser] Configuring build.
[:browser] Compiling ...
[:browser] Build completed. (341 files, 1 compiled, 0 warnings, 3,19s)
:watching
[2:0]~shadow.user=> (shadow/repl :browser)
[2:1]~cljs.user=>

提示

输入 :repl/quit 退出 REPL. 这只会退出 REPL, watch 将继续运行.

提示

你可以并行运行多个 watch "工作者", 并在任何给定时间连接/断开它们的 REPL.

没有连接的运行时错误.

[3:1]~cljs.user=> (js/alert "foo")
There is no connected JS runtime.

如果你看到这个, 你需要在浏览器中打开你的应用或启动 node 进程.

也可以在任何其他 CLJ 进程中完全使用 shadow-cljs. 只要 thheller/shadow-cljs 工件被加载到 classpath 上, 你就可以开始了.

使用 lein repl 的示例

$ lein repl
nREPL server started on port 57098 on host 127.0.0.1 - nrepl://127.0.0.1:57098
REPL-y 0.4.3, nREPL 0.6.0
Clojure 1.10.0
...
user=> (require '[shadow.cljs.devtools.server :as server])
nil
user=> (server/start!)
...
:shadow.cljs.devtools.server/started
user=> (require '[shadow.cljs.devtools.api :as shadow])
nil
user=> (shadow/compile :foo)
...

你可以通过运行 (shadow.cljs.devtools.server/stop!) 来停止嵌入式服务器. 这也将停止所有正在运行的构建进程.

如果你想切换到 CLJS REPL, 这可能需要在你用来启动服务器的工具中进行额外的设置. 由于 lein 默认使用 nREPL, 它将需要配置额外的 nREPL :middleware. 当使用 clj 时, 你可以轻松开始, 因为它不使用 nREPL.

你的依赖关系是通过 shadow-cljs.edn 配置文件根部的 :dependencies 键来管理的. 它们的声明方式与其他 Clojure 工具 (如 lein 或 boot) 使用的表示法相同.

每个依赖项都写成一个向量, 使用 [library-name "version-string"] 嵌套在一个外部向量中.

示例 :dependencies

{:source-paths ["src"]
 :dependencies [[reagent "0.9.1"]]
 :builds ...}

请注意, 源路径在整个配置中只指定了一次. 系统将使用命名空间依赖图来确定任何给定构建的最终输出中需要哪些代码.

shadow-cljs 与 npm (https://www.npmjs.com/) 生态系统完全集成, 用于管理 JavaScript 依赖.

你可以使用 npm 或 yarn 来管理你的依赖, 请参考它们各自的文档.

npm https://docs.npmjs.com/ yarn https://yarnpkg.com/en/docs

两者都通过你项目目录中的 package.json 文件来管理你的依赖. 几乎所有通过 npm 提供的包都会解释如何安装它. 这些说明现在也适用于 shadow-cljs.

安装一个 JavaScript 包

# npm
$ npm install the-thing

# yarn
$ yarn add the-thing

不需要其他任何东西. 依赖项将被添加到 package.json 文件中, 这将被用来管理它们.

提示

如果你还没有 package.json, 可以从命令行运行 npm init.

缺少 JS 依赖?

你可能会遇到与缺少 JS 依赖相关的错误. 大多数 ClojureScript 库尚未声明它们使用的 npm 包, 因为它们仍然期望使用 CLJSJS. 我们希望直接使用 npm, 这意味着你必须手动安装 npm 包, 直到库正确声明 :npm-deps 本身.

The required JS dependency "react" is not available, it was required by ...

这意味着你应该 npm install react.

提示

对于 react, 你可能需要这 3 个包: npm install react react-dom create-react-class.

shadow-cljs 服务器通过 TCP 提供一个 nREPL (https://nrepl.org) 服务器. 如果你查看启动消息, 你会看到 nREPL 的端口, 并且该端口也将存储在 target/shadow-cljs/nrepl.port 中:

$ shadow-cljs watch app
shadow-cljs - HTTP server available at http://localhost:8600
shadow-cljs - server version: <version> running at http://localhost:9630
shadow-cljs - nREPL server started on port 64967
shadow-cljs - watching build :app
[:app] Configuring build.
[:app] Compiling ...

你可以使用 shadow-cljs.edn 配置端口和额外的中间件:

{...
 :nrepl {:port 9000
         :middleware []} ; 可选的命名空间限定符号列表
 ...}

默认的全局配置文件 ~/.nrepl/nrepl.edn 或本地的 .nrepl.edn 也将在启动时加载, 并可用于配置 :middleware.

如果流行的中间件 cider-nrepl (https://github.com/clojure-emacs/cider-nrepl) 在 classpath 上找到 (例如, 它包含在 :dependencies 中), 它将被自动使用. 不需要额外的配置. 这可以通过设置 :nrepl {:cider false} 来禁用.

你可以通过在 :nrepl 选项中设置 :init-ns 来配置连接时你启动的命名空间. 它默认为 shadow.user.

{...
 :nrepl {:init-ns my.repl}
 ...}

nREPL 服务器可以通过设置 :nrepl false 来禁用.

nREPL 用法 当连接到 nREPL 服务器时, 连接总是以 Clojure REPL 开始. 切换到 CLJS REPL 的工作方式与非 nREPL 版本类似. 首先需要为给定的构建启动 watch, 然后我们需要选择此构建以将当前的 nREPL 会话切换到该构建. 选择构建后, 所有内容都将在 ClojureScript 而不是 Clojure 中求值.

(shadow/watch :the-build)
(shadow/repl :the-build)

提示

使用 :cljs/quit 返回到 Clojure.

嵌入式 nREPL 服务器 当你在提供自己的 nREPL 服务器的其他工具 (例如 lein) 中嵌入使用 shadow-cljs 时, 你需要配置 shadow-cljs 中间件. 否则你将无法在 CLJ 和 CLJS REPL 之间切换.

示例 Leiningen project.clj

(defproject my-amazing-project "1.0.0"
  ...
  :repl-options
  {:init-ns shadow.user ;; 或者任何你选择的
   :nrepl-middleware
   [shadow.cljs.devtools.server.nrepl/middleware]}
  ...)

提示

在使用 CLJS REPL 之前, 你仍然需要手动启动嵌入式服务器.

Clojure Socket REPL 在服务器模式下自动启动, 并默认使用随机端口. 工具可以通过检查 .shadow-cljs/socket-repl.port 来找到它启动的端口, 该文件将包含端口号.

你也可以通过 shadow-cljs.edn 设置一个固定端口.

{...
 :socket-repl
 {:port 9000}
 ...}

Socket REPL 可以通过设置 :socket-repl false 来禁用.

shadow-cljs HTTP 服务器支持 SSL. 它需要一个提供匹配私钥和证书的 Java Keystore.

配置了 SSL 的 shadow-cljs.edn

{...
 :ssl {:keystore "ssl/keystore.jks"
       :password "shadow-cljs"}
 ...}

以上是默认值, 所以如果你想使用它们, 只需设置 :ssl {} 即可.

你可以使用 java keytool 命令创建一个 Keystore. 创建一个受信任的自签名证书也是可能的, 但有些复杂.

• OpenSSL (https://gist.github.com/jchandra74/36d5f8d0e11960dd8f80260801109ab0) 适用于 Linux 和 Windows (通过 WSL) 的说明

创建的 Certificates.p12 (macOS) 或 localhost.pfx (Linux, Windows) 文件可以通过 keytool 实用程序转换成所需的 keystore.jks.

$ keytool -importkeystore -destkeystore keystore.jks -srcstoretype PKCS12 -srckeystore localhost.pfx

你必须使用 SAN (主题备用名称) 为 "localhost" (或任何你想要使用的主机) 生成证书. SAN 是让 Chrome 信任证书而不显示警告所必需的. 导出时使用的密码必须与分配给 Keystore 的密码匹配.

shadow-cljs 服务器启动一个主要 HTTP 服务器. 它用于提供 UI 和用于热重载和 REPL 客户端的 websockets. 默认情况下, 它监听端口 9630. 如果该端口正在使用, 它将递增一并再次尝试, 直到找到一个开放的端口.

指示所用端口的启动消息

shadow-cljs - server running at http://0.0.0.0:9630

当配置了 :ssl 时, 服务器将通过 https:// 提供服务.

提示

当使用 :ssl 时, 服务器自动支持 HTTP/2.

如果你想自己设置端口, 可以通过 :http 配置来实现.

带 :http 配置的 shadow-cljs.edn

{...
 :http {:port 12345
        :host "my.machine.local"}
 ...}

:ssl 仅将服务器切换到 https://. 如果你想保留 http:// 版本, 你可以配置一个单独的 :ssl-port.

{...
 :http {:port 12345
        :ssl-port 23456
        :host "localhost"}
 ...}

shadow-cljs可以通过 :dev-http 配置条目提供额外的基本HTTP服务器. 默认情况下, 这些服务器会从配置的路径提供所有静态文件, 当找不到资源时会回退到 index.html (这通常是开发使用浏览器推送状态的应用程序时想要的).

这些服务器在 shadow-cljs 以服务器模式运行时自动启动. 它们不特定于任何构建, 只要为每个构建使用唯一的 :output-dir, 就可以用来为多个构建提供文件.

这些只是提供静态文件的通用Web服务器. 任何实时重载或REPL逻辑都不需要它们. 任何Web服务器都可以, 这些只是为了方便而提供的.

通过 http://localhost:8000 提供 public 目录的基本示例

{...
 :dev-http {8000 "public"}
 :builds {...}}

:dev-http 期望一个从端口号到配置的映射. 该配置支持几种最常见场景的快捷方式.

从文件系统根目录提供目录

:dev-http {8000 "public"}

从 classpath 根目录提供

:dev-http {8000 "classpath:public"}

这将尝试通过 classpath 上的 public/index.html 找到对 /index.html 的请求. 这可能包括 .jar 文件中的文件.

从多个根目录提供

:dev-http {8000 ["a" "b" "classpath:c"]}

这将首先尝试查找 <project-root>/a/index.html, 然后是 <project-root>/b/index.html, 然后是 classpath 上的 c/index.html. 如果找不到, 将调用默认处理程序.

更长的配置版本期望一个映射, 支持的选项是:

• :root (字符串) 从哪个路径提供请求. 以 classpath: 开头的路径将从 classpath 而不是文件系统提供. 所有文件系统路径都相对于项目根目录.
• :roots (字符串向量) 如果你需要多个根路径, 请使用此选项而不是 :root.
• :ssl-port 当配置了 :ssl 时, 使用此端口进行 ssl 连接, 并在常规端口上提供正常的 HTTP. 如果未设置 :ssl-port 但配置了 :ssl, 则默认端口将只提供 SSL 请求.
• :host 可选. 监听的主机名. 默认为 localhost.
• :handler 可选. 一个完全限定的符号. 一个 (defn handler [req] resp), 如果找不到给定请求的资源, 则使用该函数. 默认为 shadow.http.push-state/handle (此处理程序仅响应 Accept: text/html 标头的请求).

以下两个选项仅在使用默认的内置处理程序时适用, 通常不需要更改:

• :push-state/headers (可选) 一个用于响应的 HTTP 标头映射. 默认为 text/html 标准标头.
• :push-state/index (可选) 要提供的文件. 默认为 index.html.

{...
 :dev-http
 {8080 {:root "public"
        :handler my.app/handler}}}

反向代理支持

默认情况下, 开发服务器会尝试本地提供请求, 但有时你可能想使用外部 Web 服务器来提供请求 (例如 API 请求). 这可以通过 :proxy-url 进行配置.

{...
 :dev-http
 {8000
  {:root "public"
   :proxy-url "https://some.host"}}}

一个到 http://localhost:8000/api/foo 的请求将提供由 https://some.host/api/foo 返回的内容. 所有没有本地文件的请求都将由代理服务器提供.

配置连接处理的附加可选选项有:

• :proxy-rewrite-host-header 布尔值, 默认为 true. 决定是使用原始的 Host 标头还是来自 :proxy-url 的标头. 使用上面的示例是 localhost vs some.host.
• :proxy-reuse-x-forwarded 布尔值, 默认为 false. 配置代理是否应将自身添加到 X-Forwarded-For 列表或启动一个新列表.
• :proxy-max-connection-retries 整数, 默认为 1.
• :proxy-max-request-time ms 作为整数, 默认为 30000. 30秒请求超时.

当运行 watch 时, REPL 的代码会自动注入, 通常不需要额外的配置. 有一些额外的选项可用于控制 REPL 的行为:

• :repl-init-ns 允许配置 REPL 将在哪个命名空间中启动. 默认为 cljs.user.
• :repl-pprint 使 REPL 在打印求值结果时使用 cljs.pprint 而不是常规的 pr-str. 默认为 false.

{...
 :builds
  {:app {...
         :devtools {:repl-init-ns my.app
                    :repl-pprint true
                    ...}}}}

作为开发者, 你大部分时间都花在开发模式上. 你可能熟悉像 figwheel, boot-reload 和 devtools 这样的工具. 几乎可以肯定你希望在你的构建中使用这些工具中的一个或多个.

Preloads 用于强制某些命名空间在你生成的 Javascript 的前面. 这通常用于在应用程序实际加载和运行之前注入工具和检测. preloads 选项只是 shadow-cljs.edn 的 :devtools / :preloads 部分中的一个命名空间列表, 或者在特定模块的 :preloads 键中:

{...
 :builds
  {:app {...
         :devtools {:preloads [fulcro.inspect.preload]
                    ...}}}}

例如, 只在开发期间的主模块中包含 preloads, 而不在 web worker 中:

{...
 :builds
  {:app {...
         :modules {:main {...
                          :preloads
                          [com.fulcrologic.fulcro.inspect.preload
                           com.fulcrologic.fulcro.inspect.dom-picker-preload]
                          :depends-on #{:shared}}
                   :shared {:entries []}
                   :web-worker {...
                                :depends-on #{:shared}
                                :web-worker true}}}}}

:preloads 仅应用于开发构建, 不会应用于发布构建.

从版本 2.0.130 开始, shadow-cljs 在 watch 和 compile 中自动将 cljs-devtools 添加到 preloads 中, 如果它们在 classpath 上. 你只需要确保 binaryage/devtools 在你的 dependencies 列表中. (注意, 不是 binaryage/cljs-devtools.) 如果你不想在特定目标中使用 cljs-devtools, 你可以通过在这些目标的 :devtools 部分添加 :console-support false 来抑制它.

React 和 ClojureScript 生态系统结合起来使这种事情变得超级有用. shadow-cljs 系统包含了你需要做热代码重载的一切, 无需借助外部工具.

为了使用它, 你只需运行:

shadow-cljs watch build-id

传递依赖的热重载

默认情况下, 编译后的文件和显式需要这些文件的文件会被重载. 这种方法可能不足够, 例如在为 :react-native 目标开发时. 要同时重载所有传递依赖, 使用值为 :full 的 :reload-strategy 选项, 如下所示:

这对于较大的应用可能会变慢, 仅在确实需要时使用.

{...
 :builds
  {:app
   {:target :react-native
    :init-fn some.app/init
    :output-dir "app"
    ...
    :devtools
    {:reload-strategy :full}}}}

你可以配置编译器在热代码重载引入更新代码之前和之后立即运行函数. 这对于停止/启动那些否则会闭包旧代码的东西很有用.

这些可以通过构建配置中的 :devtools 部分或直接在你的代码中通过元数据标签进行配置.

元数据

你可以在普通的 CLJS defn var 上设置某些元数据, 以通知编译器这些函数应该在实时重载时的某个时间被调用.

通过元数据配置钩子

(ns my.app)

(defn ^:dev/before-load stop []
  (js/console.log "stop"))

(defn ^:dev/after-load start []
  (js/console.log "start"))

这将在加载任何新代码之前调用 my.app/stop, 在所有新代码加载后调用 my.app/start. 你可以像这样标记多个函数, 它们将按照其命名空间的依赖顺序被调用.

还有这些的异步变体, 以防你需要做一些异步工作, 这些工作应该在继续重载过程之前完成.

异步钩子示例

(ns my.app)

(defn ^:dev/before-load-async stop [done]
  (js/console.log "stop")
  (js/setTimeout
    (fn []
      (js/console.log "stop complete")
      (done))))

(defn ^:dev/after-load-async start [done]
  (js/console.log "start")
  (js/setTimeout
    (fn []
      (js/console.log "start complete")
      (done))))

这些函数将接收一个回调函数, 当它们的工作完成时必须调用它. 如果不调用回调函数, 重载过程将不会继续.

可以用元数据标记命名空间, 这样即使它们被重新编译也永远不会被重载.

一个不可重载的 ns

(ns ^:dev/once my.thing)

(js/console.warn "will only execute once")

命名空间也可以被标记为总是重载.

一个总是可重载的 ns

(ns ^:dev/always my.thing)

(js/console.warn "will execute on every code change")

配置

除了元数据, 你还可以通过 shadow-cljs.edn 配置生命周期钩子.

• :before-load 一个函数的符号 (带命名空间), 在刷新已重新编译的文件之前运行. 此函数必须是同步的.
• :before-load-async 一个函数的符号 (带命名空间) (fn [done]), 在刷新之前运行. 此函数可以进行异步处理, 但必须调用 (done) 来指示其完成.
• :after-load 一个函数的符号 (带命名空间), 在热代码重载完成后运行.
• :after-load-async 一个函数的符号 (带命名空间) (fn [done]), 在热代码重载完成后运行. 此函数可以进行异步处理, 但必须调用 (done) 来指示其完成.
• :autoload 一个布尔值, 控制代码是否应该被热加载. 如果设置了任一回调, 则隐式设置为 true. 默认情况下为 :browser 目标启用, 设置为 false 可禁用.
• :ignore-warnings 一个布尔值, 控制带警告的代码是否应该被重载. 默认为 false.

生命周期钩子示例.

{...
 :builds
  {:app {...
         :devtools {:before-load my.app/stop
                    :after-load my.app/start
                    ...}}}}

钩子不能在 cljs.user 命名空间中声明. 钩子仅在其包含的命名空间实际包含在构建中时才使用. 如果你使用额外的命名空间, 请确保通过 :preloads 将其包含进来.

提示

如果既没有设置 :after-load 也没有设置 :before-load, 编译器将只尝试热重载 :browser 目标中的代码. 如果你仍然想要热重载但不需要任何回调, 你可以设置 :autoload true.

:build-hooks 可以使用的可能阶段是:

• :configure - 初始 :target 特定配置
• :compile-prepare - 在任何编译完成之前调用
• :compile-finish - 在所有编译完成后调用
• :optimize-prepare - 在运行 Closure Compiler 优化阶段之前调用 (:release only)
• :optimize-finish - 在 Closure 完成后调用 (:release only)
• :flush - 在所有内容刷新到磁盘后调用

在运行的 watch 中, :configure 只被调用一次. 其他任何阶段都可能为每次重新编译再次 (按顺序) 调用. build-state 将被重用, 直到构建配置更改, 此时它将被丢弃并创建一个新的.

有时希望在出现警告时构建失败, 而不是继续构建 (例如在 CI 环境中). 你可以使用 :warnings-as-errors 编译器选项来自定义处理方式.

将所有警告视为错误

{...
 :builds
  {:app
   {...
    :compiler-options {:warnings-as-errors true}}}}

仅抛出某些警告

{...
 :builds
  {:app
   {...
    :compiler-options {:warnings-as-errors #{:undeclared-var}}}}}

一组可能的警告类型关键字可以在这里 (https://github.com/clojure/clojurescript/blob/5ad96a8b3ae2e3616a19715ba9ba2471a36933a2/src/main/clojure/cljs/analyzer.cljc#L124-L163) 找到.

仅为某些命名空间抛出

{...
 :builds
  {:app
   {...
    :compiler-options {:warnings-as-errors {:ignore #{some.ns some.library.*}
                                            :warnings-types #{:undeclared-var}}}}}

:ignore 接受一组引用命名空间的符号. 可以使用直接匹配或 .* 通配符. :warning-types 的功能与上面相同, 不指定它意味着除了被忽略的命名空间外, 所有警告都会抛出.

你的网站越动态, 你的需求可能就越动态. 服务器可能不总是知道客户端最终可能需要什么. 因此, 客户端可以在需要时动态加载代码.

有几种动态加载代码的方法. shadow.lazy 是最方便和最简单的.

使用 shadow.lazy

如此处 (https://clojureverse.org/t/shadow-lazy-convenience-wrapper-for-shadow-loader-cljs-loader/3841) 所宣布的, shadow-cljs 提供了一种方便的方法来引用可能延迟加载的代码.

(ns demo.app
  (:require
    [shadow.lazy :as lazy]
    [shadow.cljs.modern :refer (js-await)]))

(def x-lazy (lazy/loadable demo.thing/x))

(defn on-event [e]
  (js-await [x (lazy/load x-lazy)]
    (x e)))

假设上面的 on-event 函数在你的应用中发生某事时被调用, 例如当用户点击一个按钮时. lazy/loadable 配置了那将是什么. lazy/load 将实际加载它. 这可能需要一个异步网络跳跃, 所以它将在此时异步进行. 在上面的 js-await 主体中, x 将是加载时 demo.thing/x 的值.

(ns demo.thing)
(defn x [e]
  "hello world")

在这种情况下, 它将是函数, 我们可以直接调用它.

你不需要担心指定此代码最终在哪个模块中. 编译器将在编译期间弄清楚. loadable 宏还允许更复杂的引用.

(def xy (lazy/loadable [demo.thing/x demo.other/y]))

(def xym (lazy/loadable {:x demo.thing/x
                         :y demo.other/y}))

如果你加载 xy, 结果将是一个包含两个东西的向量. 如果你加载 xym, 它将是一个映射. 你可以用这种方式包含跨越多个模块的 var. 加载器将确保所有模块在继续之前都已加载.

使用 shadow-cljs 的内置加载器支持

这是低级版本, 上面的版本是基于它构建的. 如果你想构建自己的异步加载抽象, 请使用它. 上面的版本使用起来更方便.

编译器支持生成使用 shadow.loader 实用程序命名空间所需的数据. 它公开了一个简单的接口, 让你可以按需加载模块.

你只需要在你的构建配置中添加 :module-loader true. 加载器将始终被注入到默认模块中 (所有其他模块都依赖的那个).

在运行时, 你可以使用 shadow.loader 命名空间来加载模块. 你也可以通过在你的页面中使用 <script> 标签来急切地加载一个模块.

{...
 :builds
  {:app
   {:target :browser
    ...
    :module-loader true
    :modules {:main {:entries [my.app]}
              :extra {:entries [my.app.extra]
                      :depends-on #{:main}}}}}}

如果你的主入口点有以下内容:

(ns my.app
  (:require [shadow.loader :as loader]))

(defn fn-to-call-on-load []
  (js/console.log "extra loaded"))

(defn fn-to-call-on-error []
  (js/console.log "extra load failed"))

那么以下表达式可用于加载代码:

加载一个模块

;; load 返回一个 goog.async.Deferred, 并且可以像 promise 一样使用
(-> (loader/load "extra")
  (.then fn-to-call-on-load fn-to-call-on-error))

加载多个模块

;; 必须是一个 JS 数组, 也返回 goog.async.Deferred
(loader/load-many #js ["foo" "bar"])

包含一个回调

(loader/with-module "extra" fn-to-call-on-load)

你可以使用 (loaded? "module-name") 检查模块是否已加载.

你可以在这篇关于代码分割 ClojureScript (https://code.thheller.com/blog/shadow-cljs/2019/03/03/code-splitting-clojurescript.html) 的博客文章中阅读更实际的示例. 这只是一个基本的概述.

加载器成本

加载器非常轻量. 它有一些你可能不使用的依赖项. 在实践中, 使用 :module-loader true 会为默认模块增加约 8KB 的 gzip 压缩大小. 这将根据你已经使用的 goog.net 和 goog.events 的多少, 以及你为发布构建使用的优化级别而有所不同.

使用标准的 ClojureScript API

生成的代码能够使用标准的 ClojureScript cljs.loader API. 有关说明, 请参阅 ClojureScript 网站上的文档 (https://clojurescript.org/news/2017-07-10-code-splitting).

使用标准 API 的优点是你的代码将与他人良好地协作. 这对库作者可能特别重要. 缺点是标准分发中的动态模块加载 API 目前比 shadow-cljs 中的支持要难用一些.

可以通过 :release-version 配置设置来为每个版本创建唯一的文件名. 通常, 你会通过 --config-merge 从命令行传入这个.

shadow-cljs release app --config-merge '{:release-version "v1"}'

示例 :modules 配置

{...
 :builds
  {:app
   {:target :browser
    ...
    :output-dir "public/js"
    :asset-path "/js"
    :modules {:main {:entries [my.app]}
              :extra {:entries [my.app.extra]
                      :depends-on #{:main}}}}}}

这将会在 public/js 中创建 main.v1.js 和 extra.v1.js 文件, 而不是通常的 main.js 和 extra.js.

你可以使用手动版本或像构建时的 git sha 这样的自动化东西. 只要确保一旦你向用户发布了某些东西, 就更新它, 因为通过缓存, 他们不会请求旧文件的新版本.

你可以向你的构建配置中添加 :module-hash-names true, 以便为每个生成的输出模块文件自动创建一个 MD5 签名. 这意味着 :main 模块将生成一个 main.<md5hash>.js, 而不仅仅是默认的 main.js.

:module-hash-names true 将包含完整的 32 位 MD5 哈希, 如果你喜欢更短的版本, 你可以指定一个 1-32 之间的数字 (例如 :module-hash-names 8). 请注意, 缩短哈希可能会增加产生冲突的机会. 我建议使用完整的哈希.

示例 :module-hash-names 配置

{...
 :builds
  {:app
   {:target :browser
    ...
    :output-dir "public/js"
    :asset-path "/js"
    :module-hash-names true
    :modules {:main {:entries [my.app]}
              :extra {:entries [my.app.extra]
                      :depends-on #{:main}}}}}}

它现在将在 :output-dir 中生成 main.<hash>.js, 而不是 main.js.

由于文件名会随着每次发布而改变, 将它们包含在你的 HTML 中会变得有点复杂. 如果你想用 shadow-cljs 外部的程序来完成这个任务, 你可以在输出清单中找到关于文件名的程序化信息. 如果你想在构建过程中完成这个任务, 请查看构建钩子, 特别是这个钩子 (https://github.com/thheller/shadow-cljs/blob/9a36743674e7bac457c43761c2ef0cce0423862a/src/main/shadow/html.clj#L28-L60).

:browser 目标现在使用 HUD 来在构建开始时显示加载指示器. 如果有警告和错误, 它也会显示.

你可以通过在 :devtools 部分设置 :hud false 来完全禁用它.

你也可以通过设置 :hud #{:errors :warnings} 来指定你关心的功能来切换某些功能. 这将显示错误/警告, 但没有进度指示器. 可用选项有 :errors, :warnings, :progress. 只有包含的选项会被启用, 其他所有选项都将被禁用.

打开文件

警告包含一个到源位置的链接, 可以点击它在你的编辑器中打开文件. 这需要一点配置.

你可以在你的 shadow-cljs.edn 项目配置中或全局地在你的主目录下的 ~/.shadow-cljs/config.edn 中配置它.

:open-file-command 配置

{:open-file-command
 ["idea" :pwd "--line" :line :file]}

:open-file-command 期望一个表示非常简单的 DSL 的向量. 字符串保持原样, 关键字被它们各自的值替换. 可以使用嵌套向量来组合多个参数, 使用 clojure.core/format 样式模式.

上面的例子会执行

$ idea /path/to/project-root --line 3 /path/to/project-root/src/main/demo/foo.cljs

emacsclient 示例

{:open-file-command
 ["emacsclient" "-n" ["+%s:%s" :line :column] :file]}

$ emacsclient -n +3:1 /path/to/project-root/src/main/demo/foo.cljs

可用的替换变量有:

• :pwd 进程工作目录 (即项目根目录)
• :file 绝对文件路径
• :line 警告/错误的行号
• :column 列号
• :wsl-file 翻译后的 WSL 文件路径. 当通过 WSL Bash 运行 shadow-cljs 时很有用. 将 /mnt/c/Users/someone/code/project/src/main/demo/foo.cljs 路径翻译成 C:\Users...
• :wsl-pwd 翻译后的 :pwd

浏览器开发工具也可以为你重载 CSS. 这默认是启用的, 在大多数情况下, 当你使用内置的开发 HTTP 服务器时, 不需要额外的配置.

任何包含在页面中的样式表如果在文件系统上被修改, 都会被重载. 最好使用绝对路径, 但相对路径也应该可以工作.

示例 HTML 片段

<link rel="stylesheet" href="/css/main.css"/>

示例 Hiccup, 因为我们不是野蛮人

[:link {:rel "stylesheet" :href "/css/main.css"}]

使用内置的开发 HTTP 服务器

:dev-http {8000 "public"}

这将导致浏览器在 public/css/main.css 改变时重载 /css/main.css.

shadow-cljs 目前不提供直接编译 CSS 的支持, 但通常的工具可以工作, 并且应该分开运行. 只需确保输出生成到正确的位置.

当你不使用内置的 HTTP 服务器时, 你可以指定 :watch-dir, 它应该是一个指向用于提供你内容的文档根目录的路径.

示例 :watch-dir 配置

{...
  {:builds
   {:app {...
          :devtools {:watch-dir "public"}}}}}

当你的 HTTP 服务器从虚拟目录提供文件, 并且文件系统路径与 HTML 中使用的路径不完全匹配时, 你可以通过设置 :watch-path 来调整路径, 它将用作前缀.

示例 public/css/main.css 在 /foo/css/main.css 下提供

{...
  {:builds
   {:app
    {...
     :devtools {:watch-dir "public"
                :watch-path "/foo"}}}}}

默认情况下, devtools 客户端将尝试通过配置的 HTTP 服务器 (通常是 localhost) 连接到 shadow-cljs 进程. 如果你使用反向代理来提供你的 HTML, 这可能是不可能的. 你可以设置 :devtools-url 来配置使用哪个 URL.

{...
 :builds
  {:app {...
         :devtools {:before-load my.app/stop
                    :after-load my.app/start
                    :devtools-url "https://some.host/shadow-cljs"
                    ...}}}}

shadow-cljs 然后将使用 :devtools-url 作为发出请求的基础. 它不是最终的 URL, 所以你必须确保所有以你配置的路径开始的请求 (例如 /shadow-cljs/*) 都被转发到 shadow-cljs 运行的主机.

到代理的传入请求

https://some.host/shadow-cljs/ws/foo/bar?asdf

必须转发到

http://localhost:9630/foo/bar?asdf

客户端将发出 WebSocket 请求以及正常的 XHR 请求来加载文件. 确保你的代理正确升级 WebSockets.

请求必须转发到主 HTTP 服务器, 而不是构建本身中配置的那个.

像 webpack 这样的工具可以潜在地对 npm 依赖进行 tree-shake, 以使其构建输出更小. 为此, :external-index 文件需要生成 ESM 代码, 而不是当前默认的 CommonJS, 即 require().

{:builds
 {:app
  {:target :browser
   :output-dir "..."
   :modules {:main {...}}
   :js-options
   {:js-provider :external
    :external-index "target/index.js"
    :external-index-format :esm}}}}

这只会在 :external-index 文件中使用 import. 对于 release 构建, 此文件将列出所有引用的导入, 对于 watch/compile, 它仍然会引用所有内容.

控制实际导出哪些代码是通过 :exports 完成的.

示例构建配置

{:source-paths ["src/main"]
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:exports {hello demo.lib/hello}}}}}}

这将生成 public/js/demo.js 文件. 名称由 :output-dir 和 :modules 映射中的键 :demo 决定.

示例 CLJS 代码

(ns demo.lib)

(defn hello []
  (js/console.log "hello world"))

(defn not-exported []
  (js/console.log "foo"))

它将可以直接在任何 ESM 环境中加载. 例如浏览器. 将其放入 public/index.html 中, 并通过 http://localhost:8000 加载它.

<script type="module">
  import { hello } from "/js/demo.js";
  hello();
</script>

使用 npx shadow-cljs watch app 你应该在加载页面时看到 hello world 记录到浏览器控制台.

注意, 这里只有 hello 是可访问的, 因为它是在 :exports 中声明的. (defn not-exported [] ...) 将是不可访问的, 并且很可能在 :advanced 发布构建中被完全移除.

模块默认导出

ES 模块有一个 "特殊" 的 default 导出, 你经常会在 JS 示例中看到它. 这可以通过像定义任何其他导出一样定义 default 导出​​来表示.

{:source-paths ["src/main"]
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:exports {default demo.lib/hello}}}}}}

导入端也随之改变

<script type="module">
  import hello from "/js/demo.js";
  hello();
</script>

许多平台或系统对这个 default 导出赋予了特殊的含义, 但它在构建配置中的声明方式与任何其他导出一样.

模块 :init-fn

有时你可能不需要任何 :exports, 而是希望代码在模块加载时自动运行. 这可以通过 :init-fn 完成.

{:source-paths ["src/main"]
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules {:demo {:init-fn demo.lib/hello}}}}}

以及 HTML

<script type="module" src="js/demo.js"></script>

它也可以与 :exports 结合使用, 以运行一个函数并仍然提供 :exports.

{:source-paths ["src/main"]
 :dev-http {8000 "public"}
 :builds
 {:app
  {:target :esm
   :output-dir "public/js"
   :modules
   {:demo
    {:init-fn demo.lib/hello
     :exports {hello demo.lib/hello}}}}}}

保持这个 HTML 将基本上在页面加载时记录两次.

<script type="module">
  import hello from "/js/demo.js";
  hello();
</script>

输出在你的 test-dir 文件夹中包括两个主要工件:

• index.html - 当且仅当尚不存在 index.html 文件时. 默认情况下, 生成的文件加载测试并在 :runner-ns 中运行 init. 你可以编辑或添加一个自定义版本, 它不会被覆盖.
• js/test.js - Javascript 测试. 测试将始终有这个名称. 模块的条目是自动生成的.

任何 web 服务器都可以, :dev-http 只是一个方便的选项.

有关完整说明, 请参阅他们的网站 (http://karma-runner.github.io). 你通常需要在你的 package.json 中有类似这样的东西:

{
  "name": "CITests",
  "version": "1.0.0",
  "description": "Testing",
  ...
  "devDependencies": {
    "karma": "^2.0.0",
    "karma-chrome-launcher": "^2.2.0",
    "karma-cljs-test": "^0.1.0",
    ...
  },
  "author": "",
  "license": "MIT"
}

所以, 你需要 Karma, 一个浏览器启动器, 和 cljs-test 集成.

构建选项是:

• :target :karma
• :output-to js 文件的路径/文件名.
• :ns-regexp (可选) 一个匹配测试命名空间的正则表达式, 默认为 "-test$

所以你可能会有类似这样的东西:

{...
 :builds
  {:ci
   {:target :karma
    :output-to "target/ci.js"
    :ns-regexp "-spec$"}}}

你还需要一个 karma.conf.js:

module.exports = function (config) {
  config.set({
    browsers: ['ChromeHeadless'],
    // 输出文件所在的目录
    basePath: 'target',
    // 文件本身
    files: ['ci.js'],
    frameworks: ['cljs-test'],
    plugins: ['karma-cljs-test', 'karma-chrome-launcher'],
    colors: true,
    logLevel: config.LOG_INFO,
    client: {
      args: ["shadow.test.karma.init"],
      singleRun: true
    }
  })
};

然后你可以如下运行测试 (假设你已经安装了工具的全局可执行文件):

$ shadow-cljs compile ci
$ karma start --single-run
12 01 2018 01:19:24.222:INFO [karma]: Karma v2.0.0 server started at http://0.0.0.0:9876/
12 01 2018 01:19:24.224:INFO [launcher]: Launching browser ChromeHeadless with unlimited concurrency
12 01 2018 01:19:24.231:INFO [launcher]: Starting browser ChromeHeadless
12 01 2018 01:19:24.478:INFO [HeadlessChrome 0.0.0 (Mac OS X 10.12.6)]: Connected on socket
TcfrjxVKmx7xN6enAAAA with id 85554456
LOG: 'Testing boo.sample-spec'
HeadlessChrome 0.0.0 (Mac OS X 10.12.6): Executed 1 of 1 SUCCESS (0.007 secs / 0.002 secs)

大多数 npm 包也会包含一些关于如何使用实际代码的说明. "旧的" CommonJS 风格只有 require 调用, 它们可以直接翻译:

var react = require("react");

(ns my.app
  (:require ["react" :as react]))

调用 require 时使用的任何 "string" 参数都会原样转移到 :require. :as 别名由你决定. 一旦我们有了它, 我们就可以像使用任何其他 CLJS 命名空间一样使用代码了!

(react/createElement "div" nil "hello world")

在 shadow-cljs 中: 始终使用 ns 形式和你提供的任何 :as 别名. 你也可以使用 :refer 和 :rename. 这与 :foreign-libs /CLJSJS 的做法不同, 在那里你将东西包含在命名空间中, 但随后在你的代码中使用全局的 js/Thing.

一些包只导出一个单一的函数, 你可以直接通过使用 (:require ["thing" :as thing]) 然后 (thing) 来调用.

最近一些包开始在它们的例子中使用 ES6 import 语句. 这些也几乎可以 1:1 翻译, 只是在默认导出方面有一个小小的区别.

以下示例可用于翻译:

此表仅适用于你正在使用的代码被打包为实际的 ES6+ 代码的情况. 如果代码被打包为 CommonJS, 那么 $default 可能不适用. 有关更多信息, 请参阅下面的部分.

这里的名称 defaultExport 或 export 是为了显示它们所代表的内容而选择的. 在 defaultExport 的情况下, 或任何其他 :as 别名, 你可以用任何你喜欢的名称替换它. 在 :refer 的情况下, 你必须使用库选择的名称或使用 :rename 来更改它. 重要的新事物是默认导出的引入以及它们在 require 方面的含义.

示例默认导出

import defaultExport from "module-name";

(:require ["module-name$default" :as defaultExport])

示例模块别名

import * as name from "module-name";

(:require ["module-name" :as name])

示例模块引用

import { export } from "module-name";

(:require ["module-name" :refer (export)])

示例模块多重引用

import { export1 , export2 } from "module-name";

(:require ["module-name" :refer (export1 export2)])

示例模块引用重命名

import { export as alias } from "module-name";

(:require ["module-name" :rename {export alias}])

示例模块引用和重命名

import { export1 , export2 as alias2 } from "module-name";

(:require ["module-name" :refer (export1) :rename {export2 alias2}])

示例模块引用和默认导出

import defaultExport, { export } from "module-name";

(:require
 ["module-name" :refer (export)]
 ["module-name$default" :as defaultExport])

示例模块别名和默认导出

import defaultExport, * as name from "module-name";

(:require
 ["module-name" :as name]
 ["module-name$default" :as defaultExport])

示例模块无用导入 (包括一个用于副作用的模块)

import from "module-name";

(:require ["module-name"])

请注意, 以前我们被困在使用捆绑代码, 其中包含了很多我们实际上不需要的代码. 现在我们的情况更好了: 一些库也被打包成允许你只包含你需要的部分, 从而在你的最终构建中产生更少的代码.

react-virtualized 是一个很好的例子:

// 你可以从 'react-virtualized' 中以命名导出的形式导入任何你想要的组件, 例如
import { Column, Table } from 'react-virtualized'

// 但如果你只使用几个 react-virtualized 组件,
// 并且你担心增加应用程序的捆绑包大小,
// 你可以直接只导入你需要的组件, 像这样:
import AutoSizer from 'react-virtualized/dist/commonjs/AutoSizer'
import List from 'react-virtualized/dist/commonjs/List'

通过我们改进的支持, 我们可以轻松地将其翻译为:

(ns my-ns
  ;; 全部
  (:require ["react-virtualized" :refer (Column Table)])
  ;; 或逐个
  (:require ["react-virtualized/dist/commonjs/AutoSizer$default" :as virtual-auto-sizer]
            ["react-virtualized/dist/commonjs/List$default" :as virtual-list]))

如果一个 :require 似乎不能正常工作, 建议在 REPL 中查看它.

$ shadow-cljs browser-repl (or node-repl)
...
[1:1]~cljs.user=> (require '["react-tooltip" :as x])
nil
[1:1]~cljs.user=> x
#object[e]
[1:1]~cljs.user=> (goog/typeOf x)
"function"
[1:1]~cljs.user=> (js/console.dir x)
nil

由于打印任意 JS 对象并不总是很有用 (如上所示), 你可以使用 (js/console.dir x) 来在浏览器控制台中获得更有用的表示. goog/typeOf 也可能很有用.

shadow-cljs 支持几种不同的方式将 npm 包包含到你的构建中. 它们可以通过 :js-options :js-provider 设置进行配置. 每个 :target 通常都会设置适合你的构建的那个, 大多数情况下你不需要接触这个设置.

目前有 3 个支持的 JS 提供者:

• :require 直接映射到 JS require("thing") 函数调用. 它是所有 node.js 目标的默认设置, 因为它可以在运行时本地解析 require. 包含的 JS 不会以任何方式处理.
• :shadow 通过 node_modules 解析 JS, 并在构建中包含每个引用文件的缩小版本. 它是 :browser 目标的默认设置. node_modules 源不会经过 :advanced 编译.
• :closure 与 :shadow 类似, 但尝试通过 Closure Compiler CommonJS/ES6 重写工具处理所有包含的文件. 它们也将通过 :advanced 编译进行处理.
• :external 只收集 JS requires 并发出一个索引文件 (通过 :external-index "foo/bar.js" 配置), 该文件旨在由任何其他 JS 构建工具处理, 并将实际提供 JS 依赖. 发出的索引文件包含一些胶水代码, 以便 CLJS 输出可以访问 JS 依赖. 外部索引文件的输出应在 CLJS 输出之前加载.

:shadow vs :closure

理想情况下, 我们希望使用 :closure 作为我们的主要 JS 提供者, 因为它将通过 :advanced 运行整个应用程序, 为我们提供最优化的输出. 然而在实践中, 通过 npm 可用的大量代码与 :advanced 编译所做的积极优化不兼容. 它们要么根本无法编译, 要么在运行时暴露出非常难以识别的细微错误.

:shadow 是一种权宜之计, 它只通过 :simple 处理代码, 并实现了更可靠的支持, 同时仍然获得了相当优化的代码. 输出与 webpack 等其他工具生成的输出相当 (或通常更好).

直到 Closure 中的支持变得更可靠之前, :shadow 是 :browser 构建的推荐 JS 提供者.

在 :browser 构建中使用 :closure 的示例配置.

{...
 :builds
  {:app
   {:target :browser
    ...
    :js-options {:js-provider :closure}
    }}}

如今许多 npm 包都提供了多种构建变体. shadow-cljs 默认会选择在 package.json 中的 main 或 browser 键下链接的变体. 这最常指的是 CommonJS 代码. 一些现代包还提供了一个 module 条目, 通常指的是 ECMAScript 代码 (意味着 "现代" JS). CommonJS 和 ESM 之间的互操作可能很棘手, 所以 shadow-cljs 默认使用 CommonJS, 但使用 ESM 可能是有益的.

这在很大程度上取决于你使用的包, 是否能正常工作. 你可以配置 shadow-cljs 通过 :entry-keys JS 选项来优先选择 module 条目. 它接受一个在 package.json 中找到的字符串键的向量, 将按顺序尝试. 默认是 ["browser" "main" "module"].

偏好 "module" 而不是 "browser" 和 "main" 的示例配置.

{...
 :builds
  {:app
   {:target :browser
    ...
    :js-options {:entry-keys ["module" "browser" "main"]} ;; 首先尝试 "module"
    }}}

请确保彻底测试并比较构建报告输出, 以检查切换时的大小差异. 结果可能会有很大的正面或负面变化.

默认情况下, shadow-cljs 将遵循 npm 约定解析所有 (:require ["thing" :as x]) require. 这意味着它将查看 <project>/node_modules/thing/package.json 并从那里跟踪代码. 为了自定义此工作方式, shadow-cljs 公开了一个 :resolve 配置选项, 让你可以覆盖事物的解析方式.

使用 CDN

假设你已经通过 CDN 在你的页面中包含了 React. 你可以再次开始使用 js/React, 但我们停止这样做是有充分理由的. 相反, 你可以继续使用 (:require ["react" :as react]), 但配置 "react" 的解析方式!

这是一个此类构建的示例 shadow-cljs.edn 配置:

{...
 :builds
  {:app
   {:target :browser
    ...
    :js-options
    {:resolve {"react" {:target :global
                         :global "React"}}}}
   :server
   {:target :node-script
    ...}}}

:app 构建现在将使用全局的 React 实例, 而 :server 构建将继续使用 "react" npm 包! 无需修改代码即可使其工作.

重定向 "require"

有时你希望对根据你的构建实际使用哪个 npm 包有更多的控制. 你可以从你的构建配置中 "重定向" 某些 require, 而无需更改代码. 这通常很有用, 如果你无法访问使用这些包的源文件, 或者你只想为一个构建更改它.

{...
 :builds
  {:app
   {:target :browser
    ...
    :js-options
    {:resolve {"react" {:target :npm
                         :require "preact-compat"}}}}}}

你也可以使用一个文件来覆盖依赖关系, 路径是相对于项目根目录的.

{...
 :builds
  {:app
   {:target :browser
    ...
    :js-options
    {:resolve {"react" {:target :file
                         :file "src/main/override-react.js"}}}}}}

限制

:shadow-js 和 :closure 对 :resolve 有完全的控制, 上面提到的一切都可以 без каких-либо недостатков. 然而, :js-provider :require 更受限制. 只有初始的 require 可以被影响, 因为在那之后, 标准的 require 就在控制之中了. 这意味着无法影响一个包可能内部 require 的东西. 因此, 不建议将其与直接使用 require 的目标 (例如 :node-script) 一起使用.

将 "react" 重定向到 "preact"

{...
 :builds
  {:app
   {:target :node-script
    ...
    :js-options
    {:resolve {"react" {:target :npm
                         :require "preact-compat"}}}}}}

react-table 的示例用法

(ns my.app
  (:require
    ["react-table" :as rt]))

上面的代码在浏览器中工作得很好, 因为每个 "react" require 都将被替换, 包括 "react-table" 内部的 "react" require. 然而, 对于 :js-provider :require, 会发出一个 require("react-table"), node 将控制它的解析方式. 这意味着它将解析为标准的 "react", 而不是我们配置的 "preact".

默认情况下, shadow-cljs 在解析 JS 包时只会查看 <project-dir>/node_modules 目录. 这可以通过 :js-options 中的 :js-package-dirs 选项进行配置. 这可以全局应用, 也可以按构建应用.

shadow-cljs.edn 中的全局配置

{...
 :js-options {:js-package-dirs ["node_modules" "../node_modules"]}
 ...}

应用于单个构建的配置

{...
 :builds
  {:app
   {...
    :js-options {:js-package-dirs ["node_modules" "../node_modules"]}}}}

相对路径将相对于项目根目录解析. 路径将从左到右尝试, 第一个匹配的包将被使用.

我们已经介绍了如何通过它们的名称访问 npm 包, 但在 classpath 上我们通过完整路径或相对于当前命名空间的路径来访问 .js 文件.

从 classpath 加载 JS

(ns demo.app
  (:require
    ["/some-library/components/foo" :as foo]
    ["./bar" :as bar :refer (myComponent)]))

提示

对于字符串 require, 扩展名 .js 将被自动添加, 但如果你愿意, 也可以指定扩展名. 请注意, 目前只支持 .js.

像 /some-library/components/foo 这样的绝对 require 意味着编译器将在 classpath 上寻找 some-library/components/foo.js; 与 node 不同, node 会尝试从本地文件系统加载文件. 同样的 classpath 规则适用, 所以文件可能在你的 :source-paths 中, 或者在某个第三方 .jar 库中.

相对 require 通过首先查看当前命名空间, 然后从中解析相对路径来解析. 在上面的例子中, 我们在 demo/app.cljs 中, ./bar require 解析为 demo/bar.js, 所以它与 (:require ["/demo/bar"]) 相同.

文件不一定要物理上位于同一目录中. 文件的查找出现在 classpath 上. 这与 node 不同, node 期望相对 require 总是解析为物理文件.

带独立路径的示例文件结构

.
├── package.json
├── shadow-cljs.edn
└── src
    └── main
        └── demo
            └── app.cljs
    └── js
        └── demo
            └── bar.js

期望 classpath 只包含可以无需编译器预处理即可使用的 JavaScript. npm 有一个非常相似的约定.

Closure Compiler 用于处理在 classpath 上找到的所有 JavaScript, 使用其 ECMASCRIPT_NEXT 语言设置. 这个设置具体意味着什么没有很好的文档记录, 但它主要代表了下一代 JavaScript 代码, 甚至可能不被大多数浏览器支持. ES6 以及大多数 ES8 功能都得到了很好的支持. 与标准 CLJS 类似, 当需要时, 这将被编译为带有 polyfills 的 ES5.

由于 Closure Compiler 不断更新, 新功能会随着时间的推移而可用. 只是不要期望最新的前沿预览功能能立即使用. 最近的一些新增功能, 如 async/await, 已经可以很好地工作了.

JS 应该使用 ES 模块语法, 使用 import 和 export. JS 文件可以包含其他 JS 文件并直接引用 CLJS 代码. 它们也可以直接访问 npm 包, 但有一个警告.

// 常规 JS require
import Foo, { something } from "./other.js";

// npm require
import React from "react";

// require CLJS 或 Closure 库 JS
import cljs from "goog:cljs.core";

export function inc(num) {
  return cljs.inc(1);
}

由于 Closure Compiler 的严格检查, 使用 import * as X from "npm"; 语法在 require CLJS 或 npm 代码时是不可能的. 在 require 其他 JS 文件时可以使用.

由于有许多流行的 JavaScript 方言 (JSX, CoffeeScript, 等) 不能被 Closure Compiler 直接解析, 我们需要先对它们进行预处理, 然后再将它们放到 classpath 上. babel (https://babeljs.io/) 在 JavaScript 世界中被广泛使用, 所以我们将以 babel 处理 .jsx 文件为例.

示例 shadow-cljs.edn 配置

{:source-paths
 ["src/main"
  "src/gen"]
 ...}

示例文件结构

.
├── package.json
├── shadow-cljs.edn
└── src
    └── main
        └── demo
            └── app.cljs
    └── js
        ├── .babelrc
        └── demo
            └── bar.jsx

注意 src/js 没有被添加到 :source-paths 中, 这意味着它不会在 classpath 上.

src/js/demo/bar.jsx

import React from "react";

function myComponent() {
  return <h1>JSX!</h1>;
}

export { myComponent };

我们运行 babel (https://babeljs.io/docs/usage/cli/) 来转换文件并将它们写入配置的 src/gen 目录. 你使用哪个目录由你决定. 我更喜欢 src/gen 用于生成的文件.

$ babel src/js --out-dir src/gen
# or during development
$ babel src/js --out-dir src/gen --watch

babel 本身是通过 src/js/.babelrc 配置的. 有关 JSX 的官方示例, 请参阅官方 JSX 示例 (https://babeljs.io/docs/plugins/transform-react-jsx/) 和有关配置文件 (https://babeljs.io/docs/config-files) 的更多信息.

JSX 最小 .babelrc

{
  "plugins": ["@babel/plugin-transform-react-jsx"]
}

一旦 babel 将 src/gen/demo/bar.js 写入, 它就可以通过 ClojureScript 使用, 甚至可以像你的 ClojureScript 源一样被热加载.

shadow-cljs 目前不提供任何运行这些转换步骤的支持. 请直接使用标准工具 (例如 babel, coffeescript, 等), 直到它提供为止.

JS 源可以通过使用 goog: 前缀导入它们的命名空间来直接访问你的所有 ClojureScript (和 Closure 库), 编译器会重写该前缀以将命名空间公开为默认的 ES6 导出.

import cljs, { keyword } from "goog:cljs.core";

// 在 JS 中构造 {:foo "hello world"}
cljs.array_map(keyword("foo"), "hello world");

提示

goog: 前缀目前只适用于 ES6 文件. require("goog:cljs.core") 将不起作用.

CLJSJS 包基本上只是从 npm 中获取包, 将它们放入一个 .jar 中, 并通过 clojars (https://clojars.org) 重新发布. 作为附赠, 它们通常会捆绑 Externs. 编译器除此之外不会对这些文件做任何事情, 只是将它们前置到生成的输出中.

当我们无法直接访问 npm 时, 这非常有用, 但它也存在某些问题, 因为并非所有包都可以轻松地与其他包组合. 一个包可能依赖于 react, 但不是通过 npm 表达这一点, 而是 (https://github.com/cljsjs/packages/tree/master/material-ui) 捆绑它们自己的 react. 如果你不小心, 你最终可能会在你的构建中包含 2 个不同版本的 react, 这可能会导致非常令人困惑的错误, 或者至少会大大增加构建大小.

除此之外, 并非每个 npm 包都通过 CLJSJS 可用, 并且保持包版本同步需要手动工作, 这意味着包通常已经过时.

shadow-cljs 完全不支持 CLJSJS, 以避免你的代码中出现冲突. 一个库可能尝试使用 "旧的" cljsjs.react, 而另一个直接使用新的 (:require ["react"]). 这又会导致你的页面上有 2 个版本的 react.

所以我们唯一缺少的是捆绑的 Externs. 在许多情况下, 由于改进的 externs 推断, 这些是不需要的. 通常那些 Externs 是使用第三方工具生成的, 这意味着它们并不完全准确.

结论: 直接使用 npm. 使用 :infer-externs auto.

你可以使用配置的 :compiler-options 部分选择优化级别:

你通常不需要设置 :optimizations, 因为 :target 已经将其设置为适当的级别.

:optimizations 仅在使用 release 命令时适用. 开发构建从未由 Closure Compiler 优化. 开发构建始终设置为 :none.

{...
 :build
  {:build-id
   {...
    :compiler-options {:optimizations :simple}}}}

有关可用优化级别的更多信息, 请参阅 Closure 编译器的文档 (https://developers.google.com/closure/compiler/docs/compilation_levels).

如果你希望在运行发布构建时在构建中具有单独的配置值, 你可以通过在构建部分中包含 :dev 和/或 :release 部分来覆盖设置:

示例 shadow-cljs.edn 构建配置

{:source-paths ["src"]
 :dependencies []
 :builds
  {:app
   {:target :browser
    :output-dir "public/js"
    :asset-path "/js"
    :modules {:base {:entries [my.app.core]}}
    ;; 这里是一些开发特定的配置
    :dev {:compiler-options {:devcards true}}
    ;; 这里是一些生产配置
    :release {:compiler-options {:optimizations :simple}}}}}

为了帮助处理 Externs, shadow-cljs 编译器提供了增强的 externs 推断功能, 这是默认启用的. 编译器将在编译时仅对你的文件执行额外的检查. 它不会警告你库中可能存在的 externs 问题.

每当编译器无法弄清楚你是在处理 JS 还是 CLJS 代码时, 你都会收到警告. 如果你没有收到任何警告, 你应该没问题.

示例代码

(defn wrap-baz [x]
  (.baz x))

示例警告

------ WARNING #1 --------------------------------------------------------------
 File: ~/project/src/demo/thing.cljs:23:3
--------------------------------------------------------------------------------
 21 |
 22 | (defn wrap-baz [x]
 23 |   (.baz x))
---------^----------------------------------------------------------------------
 Cannot infer target type in expression (. x baz)
--------------------------------------------------------------------------------

在 :advanced 中, 编译器可能会将 .baz 重命名为更短的东西, 而 Externs 告诉编译器这是一个不应重命名的外部属性.

警告告诉你编译器无法识别 x 绑定中的 baz 属性. 如果你向正在执行原生互操作的对象添加类型提示, shadow-cljs 可以生成适当的 externs.

类型提示以帮助生成 externs

(defn wrap-baz [x]
  (.baz ^js x))

^js 类型提示将导致编译器生成正确的 externs, 警告将消失. 该属性现在可以安全地不被重命名. 你可以直接标记互操作形式, 或者标记变量首次绑定的位置.

多个互操作调用

(defn wrap-baz [x]
  (.foo ^js x)
  (.baz ^js x))

为每个互操作调用添加注解可能很乏味, 所以你可以注解变量绑定本身. 它将在该变量的整个作用域中使用. 两个调用的 Externs 仍将被生成. 所以, 你可以这样做:

直接注解 x

(defn wrap-baz [^js x]
  (.foo x)
  (.baz x))

不要用 ^js 注解所有东西. 有时你可能在 CLJS 或 ClosureJS 对象上进行互操作. 那些不需要 externs. 如果你确定你正在处理一个 CLJS 对象, 请改用 ^clj 提示. 错误地使用 ^js 并不是世界末日, 但当一个变量可以被重命名而没有时, 它可能会影响一些优化.

使用 js/ 调用全局对象不需要类型提示.

不需要提示, externs 会自动推断

(js/Some.Thing.coolFunction)

:require 绑定上的调用也会被自动推断.

:as 和 :refer 绑定不需要提示

(ns my.app
  (:require ["react" :as react :refer (createElement)]))

(react/createElement "div" nil "hello world")
(createElement "div" nil "hello world")

一些库以单独的 .js 文件形式提供 Externs. 你可以通过 :externs 编译器选项将它们包含到你的构建中.

手动 Externs 配置

{...
 :builds
  {:app
   {:target :browser
    ...
    :compiler-options {:externs ["path/to/externs.js" ...]}
    }}}

提示

编译器首先会查找相对于项目根目录的文件. 如果没有找到文件, 它也会尝试从 classpath 加载它们.

手动编写 Externs 可能很有挑战性, shadow-cljs 提供了一种更方便的方式来编写它们. 首先创建一个 externs/<your-build>.txt, 所以构建 :app 将是 externs/app.txt. 在该文件中, 每行应该是一个指定不应重命名的 JS 属性的单词. 全局变量应以 global: 为前缀:

示例 externs/app.txt

# this is a comment
foo
bar
global:SomeGlobalVariable

在此示例中, 编译器将停止重命名 something.foo() 和 something.bar().

启动 nREPL 和一个 ClojureScript REPL.

M-x cider-jack-in-cljs

CIDER 会提示你输入 ClojureScript REPL 的类型:

Select ClojureScript REPL type:

输入 shadow.

Select shadow-cljs build:

输入你的构建目标的名称, 例如, app.

Emacs 现在应该打开一个到 shadow-cljs 服务器的新 nREPL 连接, 并引导进入一个 ClojureScript REPL 环境:

shadow.user> To quit, type: :cljs/quit
[:selected :app]
cljs.repl>

你现在应该能够求值 ClojureScript, 跳转到 var 的定义 (使用 cider-find-var) 等等.

例如, 在浏览器中显示一个警报:

cljs.repl> (js/alert "Jurassic Park!")

你可以通过在项目根目录创建一个 .dir-locals.el 文件来简化启动流程.

((nil . ((cider-default-cljs-repl . shadow)
         (cider-shadow-default-options . "<your-build-name-here>"))))

或者, 当监视多个构建时:

((nil . ((cider-default-cljs-repl . shadow)
         (cider-shadow-default-options . "<your-build-name-here>")
         (cider-shadow-watched-builds . ("<first-build>" "<other-build>")))))

阅读关于 Emacs 和 shadow-cljs, 使用 .dir-locals.el 文件的 Cider 文档 (https://docs.cider.mx/cider/1.1/cljs/shadow-cljs.html)

如果你想通过 deps.edn (https://clojure.org/guides/deps_and_cli) 管理你的依赖, 你可以使用自定义的 cljs-repl 初始化形式. 创建一个 :dev 别名, 带有 "dev" 的额外源路径, 并添加以下命名空间

(ns user
  (:require [shadow.cljs.devtools.api :as shadow]
            [shadow.cljs.devtools.server :as server]))

(defn cljs-repl
  "连接到给定的 build-id. 默认为 ~:app~."
  ([]
   (cljs-repl :app))
  ([build-id]
   (server/start!)
   (shadow/watch build-id)
   (shadow/nrepl-select build-id)))

假设你的 build-id 是 :app, 将以下内容添加到你的 .dir-locals.el 中

((nil . ((cider-clojure-cli-global-options . "-A:dev")
         (cider-preferred-build-tool . clojure-cli)
         (cider-default-cljs-repl . custom)
         (cider-custom-cljs-repl-init-form . "(do (user/cljs-repl))")
         (eval . (progn
                   (make-variable-buffer-local 'cider-jack-in-nrepl-middlewares)
                   (add-to-list 'cider-jack-in-nrepl-middlewares
                                "shadow.cljs.devtools.server.nrepl/middleware"))))))

cider-jack-in-cljs 应该就可以直接工作了.

你需要 VS Code 和 Calva (https://marketplace.visualstudio.com/items?itemName=betterthantomorrow.calva#overview) 扩展.

启动 REPL 的最简单方法是使用 Calva 的 Jack-in 命令, 然后选择 shadow-cljs 项目类型. 这将启动 shadow-cljs 监视器并注入必要的 cider-nrepl 依赖.

如果你想自己启动 REPL, 你可以:

1. 使用 Calva 命令 Copy Jack-in Command to Clipboard
2. 从终端启动 REPL (VS Code 的内置终端对此非常适用)
3. 使用 Calva 命令 Connect to a Running REPL

一旦 shadow 完成其初始编译, 启动应用 (在浏览器, node, 或任何地方, 取决于你的应用).

Calva 会提示你附加 REPL 连接到哪个构建. Calva 有一个命令 (和一个状态栏按钮) 用于切换附加的构建.

开始 hack 吧!

有关如何使用 Calva 的信息, 请参阅 calva.io (https://calva.io).

使用你喜欢的方法在 Vim/Neovim 中安装插件来安装 Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978).

作为一个 nREPL (https://nrepl.org/) 客户端, Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978) 依赖于 CIDER-nREPL (https://docs.cider.mx/cider-nrepl/) (它是一个提供通用的, 与编辑器无关的 REPL 操作的 nREPL 中间件), 因此你需要将此依赖项包含在 ~/.shadow-cljs/config.edn 或 shadow-cljs.edn 中 (如下一个子部分所示). 一旦看到此依赖项, Shadow-CLJS 将注入所需的 CIDER-nREPL 中间件.

按照官方 Shadow-CLJS 快速入门 (https://github.com/thheller/shadow-cljs#quick-start) 指南创建示例应用, 并按如下方式修改其 shadow-cljs.edn:

;; shadow-cljs configuration
{:source-paths
 ["src/dev"
  "src/main"
  "src/test"]

 ;; ADD - Fireplace.vim 所需的 CIDER-nREPL 中间件
 :dependencies
 [[cider/cider-nrepl "0.22.4"]]

 ;; ADD - Fireplace.vim 连接的 REPL 服务器的端口 (例如, 3333)
 :nrepl
 {:port 3333}

 ;; ADD - 为应用提供服务的开发时 HTTP 服务器的端口 (例如, 8080)
 :dev-http
 {8080 "public"}

 :builds
 {:frontend ; NOTE - 这是下面各处引用的构建 ID.
  {:target :browser
   :modules {:main {:init-fn acme.frontend.app/init}}}}}

完成后, 启动应用 (注意 shadow-cljs.edn 中指定的 Shadow-CLJS 构建 ID, frontend):

npx shadow-cljs watch frontend

在浏览器中打开应用 http://localhost:8080/. 如果没有这一步, 如果你尝试从 Vim/Neovim 连接到 REPL 服务器, 你会从 Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978) 得到以下错误消息:

No application has connected to the REPL server.
Make sure your JS environment has loaded your compiled ClojureScript code.

在 Vim/Neovim 中打开一个 ClojureScript 源文件, 并执行以下命令以将 Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978) 连接到 REPL 服务器 (注意 shadow-cljs.edn 中指定的 REPL 服务器端口, 3333):

:Connect 3333
=>
Connected to nrepl://localhost:3333/
Scope connection to: ~/code/clojurescript/acme-app (ENTER)

这将创建一个 Clojure (而不是 ClojureScript) REPL 会话. 执行以下命令以向会话添加 ClojureScript 支持 (注意 shadow-cljs.edn 中指定的 Shadow-CLJS 构建 ID, frontend):

:CljEval (shadow/repl :frontend)
=>
To quit, type: :cljs/quit
[:selected :frontend]
Press ENTER or type command to continue

你现在应该能够对 REPL 服务器执行 Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978) 命令了. 请参考 Fireplace.vim (https://www.vim.org/scripts/script.php?script_id=4978) 文档以获取可以执行的完整命令列表.

当使用 deps.edn 通过 shadow-cljs.edn 中的 :deps 键来管理你的依赖时, 建议直接使用 clj 工具进行进一步的诊断. 首先你需要检查你通过 shadow-cljs.edn 应用了哪些别名. 所以如果你设置了 :deps {:aliases [:dev :cljs]}, 你在运行进一步命令时需要指定这些别名.

首先, 你应该确保在 deps.edn 中直接声明的所有依赖项都具有预期的版本. 有时传递依赖会导致包含有问题的版本. 你可以通过以下方式列出所有依赖项:

列出所有活动的依赖项

$ clj -A:dev:cljs -Stree

这将列出所有依赖项. 追踪这个问题有点手动, 但你需要验证你是否获得了上面提到的依赖项的正确版本.

有关更多信息, 请参考官方的 tools.deps (https://clojure.org/reference/deps_and_cli) 文档.

当使用 project.clj 来管理你的依赖时, 你需要在使用 lein 直接诊断问题时指定你从 shadow-cljs.edn 配置的 :lein profiles. 例如 :lein {:profile "+cljs"} 将要求每个命令都使用 lein with-profile +cljs.

deps 的示例列表

# no profile
$ lein deps :tree
# with profile
$ lein with-profile +cljs deps :tree

这通常会在顶部列出所有当前的冲突, 并在底部提供带有依赖树的建议. 这些建议并不总是完全准确, 所以不要被误导, 也不要向 thheller/shadow-cljs 工件添加排除项.

有关更多信息, 请参考 Leiningen (https://leiningen.org/) 文档.

Clojure 中的 REPL 正如其名: 读取一个形式, 求值它, 打印结果, 循环再做一次.

然而, 在 ClojureScript 中, 事情要复杂一些, 因为编译发生在 JVM 上, 但结果是在 JavaScript 运行时中求值的. 为了 "模拟" 普通的 REPL 体验, 需要做几个步骤. 尽管 shadow-cljs 中的实现与常规 CLJS 有些不同, 但基本原则保持不变.

首先你需要一个 REPL 客户端. 这可以是 CLI (例如 shadow-cljs cljs-repl app) 或你的编辑器通过 nREPL 连接. 客户端将始终直接与 shadow-cljs 服务器对话, 并处理其余部分. 从客户端的角度来看, 它仍然像一个常规的 REPL, 但在后台发生了一些步骤.

1. 读取: 一切都从从给定的 InputStream 读取一个 CLJS 形式开始. 这要么是直接从 stdin 的阻塞读取, 要么是在 nREPL 的情况下从字符串读取. 字符流被转换成实际的数据结构, "(+ 1 2)" (一个字符串) 变成 (+ 1 2) (一个列表).
2. 编译: 该形式然后在 shadow-cljs JVM 端被编译并转换成一组指令.
3. 传出: 这些指令被传输到一个连接的 JavaScript 运行时. 这可以是一个浏览器或一个 node 进程.
4. 求值: 连接的运行时将接收到的指令并求值它们.
5. 打印: 求值结果在 JS 运行时中作为字符串打印.
6. 传回: 打印的结果被传输回 shadow-cljs JVM 端.
7. 回复: JVM 端将接收到的结果转发给初始调用者, 结果被打印到适当的 OutputStream (或作为 nREPL 消息发送).
8. 循环: 从 1) 开始重复.

shadow-cljs JVM 端的事情将需要一个正在运行的 watch 来处理给定的构建, 它将处理所有相关的 REPL 命令. 它使用一个专用的线程并管理在开发期间可能发生的所有给定事件 (例如 REPL 输入, 文件更改等).

然而, 编译后的 JS 代码也必须由一个 JS 运行时 (例如浏览器或 node 进程) 加载, 并且该 JS 运行时必须连接回正在运行的 shadow-cljs 进程. 大多数 :target 配置都会默认添加必要的代码, 并且应该自动连接. 连接是如何发生的取决于运行时, 但通常是使用 WebSocket 连接到正在运行的 shadow-cljs HTTP 服务器.

一旦连接上, REPL 就可以使用了. 请注意, 重新加载 JS 运行时 (例如手动刷新浏览器页面) 将清除运行时的所有 REPL 状态, 但一些编译器端的状态将保持不变, 直到 watch 也被重启.

一个 watch 进程可以连接多个 JS 运行时. shadow-cljs 默认选择第一个连接的 JS 运行时作为求值目标. 如果你在多个浏览器中打开一个给定的 :browser 构建, 只有第一个将用于求值代码. 或者你可能在 iOS 和 Android 上同时开发一个 :react-native 应用. 只有一个运行时可以求值, 如果那个断开连接, 下一个将根据它们连接的时间接管.

没有应用程序连接到 REPL 服务器. 请确保你的 JS 环境已加载你编译的 ClojureScript 代码.

这个错误消息仅仅意味着没有 JS 运行时 (例如浏览器) 连接到 shadow-cljs 服务器. 你的 REPL 客户端已成功连接到 shadow-cljs 服务器, 但如上所述, 我们仍然需要一个 JS 运行时来实际求值任何东西.

常规的 shadow-cljs 构建不管理任何它们自己的 JS 运行时, 所以你负责运行它们.

• :target :browser 对于 :browser 构建, watch 进程会将给定的代码编译到配置的 :output-dir (默认为 public/js). 生成的 .js 必须在浏览器中加载. 一旦加载, 浏览器控制台应该显示一个 WebSocket 连接的消息. 如果你使用任何类型的自定义 HTTP 服务器或有过于激进的防火墙阻止连接, 你可能需要设置一些额外的配置 (例如通过 :devtools-url). 目标是能够连接到主 HTTP 服务器.
• :target :node-script, :node-library 这些目标会生成一个旨在在 node 进程中运行的 .js 文件. 然而, 鉴于选项的多样性, 你需要自己运行它们. 例如, 一个 :node-script 你会通过 node the-script.js 运行, 启动时它会尝试连接到 shadow-cljs 服务器. 你应该在启动时看到一个 WebSocket 连接的消息. 输出被设计为只在编译它们的机器上运行, 不要将 watch 输出复制到其他机器.
• :target :react-native 生成的 <:output-dir>/index.js 文件需要被添加到你的 react-native 应用中, 然后在实际的设备或模拟器上加载. 启动时, 它也会尝试连接到 shadow-cljs 服务器. 你可以通过 react-native log-android|log-ios 检查日志输出, 并且在应用运行时应该看到一个 WebSocket 连接的消息. 如果你在启动时看到一个与 websocket 相关的错误, 那么它可能未能连接到 shadow-cljs 进程. 当 IP 检测选择了不正确的 IP 时, 可能会发生这种情况. 你可以通过 shadow-cljs watch app --verbose 检查使用了哪个 IP, 并通过 shadow-cljs watch app --config-merge '{:local-ip "1.2.3.4"}' 来覆盖它.

Leiningen 默认在发布前通过 GPG 签署库, 这是一个很好的默认设置, 但鉴于设置起来可能很麻烦, 而且实际上没有多少人验证签名, 你可以通过在 project.clj 中添加一个简单的 :repositories 配置来禁用该步骤.

(defproject your.cool/library "1.0.0"
  ...
  :repositories
  {"clojars" {:url "https://clojars.org/repo"
              :sign-releases false}}
  ...)

如果你编写测试或使用其他与开发相关的代码, 请确保将它们保留在 src/dev 或 src/test 中, 以避免将它们与库一起发布.

另外, 避免向 resources/* 生成输出, 因为 Leiningen 和其他工具可能会将这些文件包含到 .jar 中, 这可能会给下游用户带来问题. 你的 .jar 应该只包含实际的源文件, 没有编译代码.

你可以并且应该通过运行 lein jar 并通过 jar -tvf target/library-1.0.0.jar 检查最终进入其中的文件来验证一切是否干净.