nbb__test_deploy
Advanced tools
Not babashka. Node.js babashka!?
Ad-hoc CLJS scripting on Node.js.
Run npx nbb to run nbb on your own machine, or try it in a browser on
Replit!
Nbb's main goal is to make it easy to get started with ad hoc CLJS scripting on Node.js.
Additional goals and features are:
Nbb requires Node.js v14 or newer.
CLJS code is evaluated through SCI, the same interpreter that powers babashka. Because SCI works with advanced compilation, the bundle size, especially when combined with other dependencies, is smaller than what you get with self-hosted CLJS. That makes startup faster. The trade-off is that execution is less performant and that only a subset of CLJS is available (e.g. no deftype, yet).
Install nbb from NPM:
$ npm install nbb -g
Omit -g for a local install.
Try out an expression:
$ nbb -e '(+ 1 2 3)'
6
And then install some other NPM libraries to use in the script. E.g. with the following package.json:
{
"dependencies": {
"csv-parse": "^5.0.4",
"shelljs": "^0.8.5",
"term-size": "^3.0.1",
"zx": "^5.3.0"
}
}
Create a script which uses the NPM libraries:
(ns example
(:require ["csv-parse/sync$default" :as csv]
["fs" :as fs]
["path" :as path]
["shelljs$default" :as sh]
["term-size$default" :as term-size]
["zx" :refer [$]]
["zx$fs" :as zxfs]
[nbb.core :refer [*file*]]))
(prn (path/resolve "."))
(prn (term-size))
(println (count (str (fs/readFileSync *file*))))
(prn (sh/ls "."))
(prn (csv/parse "foo,bar"))
(prn (zxfs/existsSync *file*))
($ #js ["ls"])
Call the script:
$ nbb script.cljs
"/private/tmp/test-script"
#js {:columns 216, :rows 47}
510
#js ["node_modules" "package-lock.json" "package.json" "script.cljs"]
#js [#js ["foo" "bar"]]
true
$ ls
node_modules
package-lock.json
package.json
script.cljs
The :default foo syntax is shadow-cljs only and not supported by vanilla CLJS
(and nbb doesn't support it either). The $default syntax is a recent addition
to CLJS and should work in shadow-cljs too: this is why nbb supports it too.
See here for more info on that syntax.
Nbb implements :require via dynamic import (import() in JS). This is why you
need to add $default to imports when you want to import the default object
from a module.
Nbb has first class support for macros: you can define them right inside your .cljs file, like you are used to from JVM Clojure. Consider the plet macro to make working with promises more palatable:
(defmacro plet
[bindings & body]
(let [binding-pairs (reverse (partition 2 bindings))
body (cons 'do body)]
(reduce (fn [body [sym expr]]
(let [expr (list '.resolve 'js/Promise expr)]
(list '.then expr (list 'clojure.core/fn (vector sym)
body))))
body
binding-pairs)))
Using this macro we can make async code look more like sync code. Consider this puppeteer example:
(-> (.launch puppeteer)
(.then (fn [browser]
(-> (.newPage browser)
(.then (fn [page]
(-> (.goto page "https://clojure.org")
(.then #(.screenshot page #js{:path "screenshot.png"}))
(.catch #(js/console.log %))
(.then #(.close browser)))))))))
Using plet this becomes:
(plet [browser (.launch puppeteer)
page (.newPage browser)
_ (.goto page "https://clojure.org")
_ (-> (.screenshot page #js{:path "screenshot.png"})
(.catch #(js/console.log %)))]
(.close browser))
See the puppeteer example for the full code.
Since v0.0.36, nbb includes promesa which is a library to deal with
promises. The above plet macro is similar to promesa.core/let.
$ time nbb -e '(+ 1 2 3)'
6
nbb -e '(+ 1 2 3)' 0.17s user 0.02s system 109% cpu 0.168 total
The baseline startup time for a script is about 170ms seconds on my laptop. When
invoked via npx this adds another 300ms or so, so for faster startup, either
use a globally installed nbb or use $(npm bin)/nbb script.cljs to bypass
npx.
Nbb does not depend on any NPM dependencies. All NPM libraries loaded by a script are resolved relative to that script. When using the Reagent module, React is resolved in the same way as any other NPM library.
To load .cljs files from local paths or dependencies, you can use the
--classpath argument. The current dir is added to the classpath automatically.
So if there is a file foo/bar.cljs relative to your current dir, then you can
load it via (:require [foo.bar :as fb]). Note that nbb uses the same naming
conventions for namespaces and directories as other Clojure tools: foo-bar in
the namespace name becomes foo_bar in the directory name.
To load dependencies from the Clojure ecosystem, you can use the Clojure CLI or babashka to download them and produce a classpath:
$ classpath="$(clojure -A:nbb -Spath -Sdeps '{:aliases {:nbb {:replace-deps {com.github.seancorfield/honeysql {:git/tag "v2.0.0-rc5" :git/sha "01c3a55"}}}}}')"
and then feed it to the --classpath argument:
$ nbb --classpath "$classpath" -e "(require '[honey.sql :as sql]) (sql/format {:select :foo :from :bar :where [:= :baz 2]})"
["SELECT foo FROM bar WHERE baz = ?" 2]
Currently nbb only reads from directories, not jar files, so you are
encouraged to use git libs. Support for .jar files will be added later. You
can find a workaround for that here.
The name of the file that is currently being executed is available via
nbb.core/*file* or on the metadata of vars:
(ns foo
(:require [nbb.core :refer [*file*]]))
(prn *file*) ;; "/private/tmp/foo.cljs"
(defn f [])
(prn (:file (meta #'f))) ;; "/private/tmp/foo.cljs"
Nbb includes reagent.core which will be lazily loaded when required. You
can use this together with ink to create
a TUI application:
$ npm install ink
ink-demo.cljs:
(ns ink-demo
(:require ["ink" :refer [render Text]]
[reagent.core :as r]))
(defonce state (r/atom 0))
(doseq [n (range 1 11)]
(js/setTimeout #(swap! state inc) (* n 500)))
(defn hello []
[:> Text {:color "green"} "Hello, world! " @state])
(render (r/as-element [hello]))
Working with callbacks and promises can become tedious. Since nbb v0.0.36 the
promesa.core namespace is included with the let and do! macros. An example:
(ns prom
(:require [promesa.core :as p]))
(defn sleep [ms]
(js/Promise.
(fn [resolve _]
(js/setTimeout resolve ms))))
(defn do-stuff
[]
(p/do!
(println "Doing stuff which takes a while")
(sleep 1000)
1))
(p/let [a (do-stuff)
b (inc a)
c (do-stuff)
d (+ b c)]
(prn d))
$ nbb prom.cljs
Doing stuff which takes a while
Doing stuff which takes a while
3
Also see API docs.
In the REPL it can be convenient to bind the resolved value of promises to a var. You can do that like this:
(defmacro defp [binding expr]
`(-> ~expr (.then (fn [val]
(def ~binding val)))))
(defp browser (.launch puppeteer #js {:headless false}))
(defp page (.newPage browser))
(.goto page "https://clojure.org")
Since nbb v0.1.0 cljs-bean is available.
See the example for an example.
Since nbb v0.0.75 applied-science/js-interop is available:
(ns example
(:require [applied-science.js-interop :as j]))
(def o (j/lit {:a 1 :b 2 :c {:d 1}}))
(prn (j/select-keys o [:a :b])) ;; #js {:a 1, :b 2}
(prn (j/get-in o [:c :d])) ;; 1
Most of this library is supported in nbb, except the following:
:syms.-x notation. In nbb, you must use keywords.See the example of what is currently supported.
Nbb supports the following reader conditional features: :org.babashka/nbb and
:cljs in that order of priority:
#?(:org.babashka/nbb 1 :cljs 2) ;;=> 1
#?(:cljs 2 :org.babashka/nbb 1) ;;=> 2
It is possible to use the -main function as the software (script) start point when using the m parameter of nbb passing your software namespace.
(ns example)
(defn -main
[& args]
(prn "print in -main"))
Execute:
nbb -m example
See doc/testing.
To start a console REPL, simply run nbb.
To start a socket server REPL, run:
$ nbb socket-repl :port 1337
Nbb exposes the nbb.repl namespace to programmatically start a REPL. See
API for more info. An example:
(ns example
(:require [nbb.repl :as repl]
[promesa.core :as p]))
(defn available-in-repl [] :yolo)
(p/do!
(repl/repl)
;; type (available-in-repl) in the REPL and it will return :yolo
(println "The end"))
The repl function returns a promise. The promesa.core/do! macro waits for the REPL to finish and after that "The end" is printed:
$ nbb example.cljs
example=> (available-in-repl)
:yolo
example=> The end
To launch a REPL from a Node.js script, you can use loadString or loadFile:
import { loadString } from 'nbb'
await loadString(`
(require '[nbb.repl :refer [repl]])
(repl)
`)
console.log('The end!')
$ node repl.mjs
user=> (+ 1 2 3)
6
user=> The end!
The nREPL server probably still has rough edges. Please report issues here.
An nREPL server can be started with:
$ nbb nrepl-server :port 1337
After that you can connect using an nREPL client:
$ lein repl :connect 1337
and evaluate expressions.
Running nREPL in Docker container is supported with the optional :host argument.
$ nbb nrepl-server :port 1337 :host 0.0.0.0
In Calva connect to the REPL with:
Currently CIDER needs the following workaround.
See this tweet.
The following projects are using nbb or are supporting it as a development platform:
See API documentation with a list of built-in libraries.
See this gist on how to convert an nbb script or project to shadow-cljs.
See Publishing an nbb project to npm.
See Creating a standalone executable with caxa.
See Nbb on AWS Lambda.
See Nbb on Google Cloud Functions.
See Deploying an nbb app to fly.io.
Prequisites:
To build:
bb releaseRun bb tasks for more project-related tasks.
Copyright © 2021-2022 Michiel Borkent
Distributed under the EPL License. See LICENSE.
FAQs
Babashka-like tool for Node.js.
We found that nbb__test_deploy demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.