babashka/nbb babashka/nbb

  • Stars
    star
    772
  • Rank 58,693 (Top 2 %)
  • Language
    Clojure
  • License
    Eclipse Public Li...
  • Created about 3 years ago
  • Updated about 1 year ago
Twitter logo Share LinkedIn logo Share Facebook logo Share
babashka/nbb
github

babashka

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Scripting in Clojure on Node.js using SCI

Not babashka. Node.js babashka!?

Ad-hoc CLJS scripting on Node.js.

Try it out

Run npx nbb to run nbb on your own machine, or try it in a browser on Replit!

Goals and features

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:

  • Fast startup without relying on a custom version of Node.js.
  • Small artifact (current size is around 1.2MB).
  • First class macros.
  • Support building small TUI apps using Reagent.
  • Complement babashka with libraries from the Node.js ecosystem.

Community

Requirements

Nbb requires Node.js v14 or newer.

Additionally, in the case of downloading Clojure dependencies, it requires the installation of babashka.

How does this tool work?

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).

Usage

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.3.0",
    "shelljs": "^0.8.5",
    "term-size": "^3.0.2",
    "zx": "^7.1.1"
  }
}

Create a script which uses the NPM libraries:

(ns example
  (:require ["csv-parse/sync" :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

What does $default mean?

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.

Macros

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.

Startup time

$ 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.

Libraries

See API documentation with a list of built-in Clojure libraries.

Dependencies

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.

Clojure dependencies

Note: this feature relies on the presence of the babashka bb executable in the system's PATH.

To load dependencies from the Clojure ecosystem, you can create an nbb.edn:

{:deps {com.github.seancorfield/honeysql {:mvn/version "2.2.868"}}}

Similar to node_modules, nbb will unpack these dependencies in an .nbb directory and will load them from there.

Classpath

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.

Current file

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"

Reagent

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 promises

Promesa

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.

REPL

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")

Cljs-bean

Since nbb v0.1.0 cljs-bean is available.

See the example for an example.

Js-interop

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:

  • destructuring using :syms
  • property access using .-x notation. In nbb, you must use keywords.

See the example of what is currently supported.

Reader conditionals

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

Main function

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

Testing

See doc/testing.

REPL

Console REPL

To start a console REPL, simply run nbb.

Socket REPL

To start a socket server REPL, run:

$ nbb socket-repl :port 1337

REPL API

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!

nREPL

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

Calva

In Calva connect to the REPL with:

  • Connect to a Running REPL Server not in Project > ClojureScript nREPL server

CIDER

Use cider-jack-in-cljs as usual to start the nbb nREPL server from within an nbb project

or start an nREPL server from the command line with

$ nbb nrepl-server

and use cider-connect-cljs with a ClojureScript REPL type of nbb to connect to it.

CIDER prior to v1.6.0, needs the following workaround.

See also this article by Benjamin Scherdtner.

Vim Iced

See this tweet.

nREPL API

You can programmatically start and stop an nREPL server through:

(require '[nbb.nrepl-server :as nrepl])
(nrepl/start-server! {:port 1337})
(nrepl/stop-server!)

In a JavaScript project you can do the above through:

import { loadString } from 'nbb'

globalThis.inspectMyProcess = () => {
  return {version: process.version};
}

await loadString(`

(require '[nbb.nrepl-server :as nrepl])
(nrepl/start-server! {:port 1337})

`)

If you calling this from a CommonJS module, you can use dynamic import:

async function nREPL() {
  const { loadString } = await import('nbb');
  await loadString(`
  (require '[nbb.nrepl-server :as nrepl])
  (nrepl/start-server! {:port 1337})
`);
}

nREPL();

And then you can connect with an nREPL client:

$ node scratch.mjs &
nREPL server started on port 1337 on host 127.0.0.1 - nrepl://127.0.0.1:1337

$ lein repl :connect 1337
Connecting to nREPL at 127.0.0.1:1337
user=> js/process.argv
#js ["/Users/borkdude/.nvm/versions/node/v17.8.0/bin/node" "/Users/borkdude/dev/nbb/scratch.mjs"]
user=> (js/inspectMyProcess)
#js {:version "v17.8.0"}

Projects using nbb

The following projects are using nbb or are supporting it as a development platform:

Examples

Calling nbb from JavaScript

You can load nbb from JavaScript. Exposed functions are loadFile, loadString, addClassPath, getClassPath and printErrorReport.

An example:

Clojure:

(ns example)

(defn foo [] "Hello")

;; this JS object is the return value of loadFile:
#js {:foo foo}

JavaScript:

import { loadFile } from 'nbb'

// destructure JS object returned from .cljs file:
const { foo } = await loadFile('example.cljs')

// execute the foo function
foo();

Printing errors

Here's an example of how to print errors from the JS API:

import { loadString, printErrorReport } from 'nbb'

try {
  await loadString(`(assoc :foo :bar)`)
}
catch (e) {
  printErrorReport(e);
  process.exit(1);
}

Videos

Articles

Podcasts

Migrating to shadow-cljs

See this gist on how to convert an nbb script or project to shadow-cljs.

Publishing an nbb project to npm

See Publishing an nbb project to npm.

Creating a standalone executable with caxa

See Creating a standalone executable with caxa.

Nbb on AWS Lambda

See Nbb on AWS Lambda.

Nbb on Google Cloud Functions

See Nbb on Google Cloud Functions.

Develop

Nbb on fly.io

See Deploying an nbb app to fly.io.

Build

Prequisites:

  • babashka >= 0.4.0
  • Clojure CLI >= 1.10.3.933
  • Node.js 16.5.0 (lower version may work, but this is the one I used to build)

To build:

  • Clone and cd into this repo
  • bb release

Run bb tasks for more project-related tasks.

Credits

  • Original babashka logo by Nikita Prokopov. Node.js modifications by MnRa.

License

Copyright Β© 2021-2022 Michiel Borkent

Distributed under the EPL License. See LICENSE.

More Repositories

1

babashka

Native, fast starting Clojure interpreter for scripting
Clojure
3,642
star
2

sci

Configurable Clojure/Script interpreter suitable for scripting and Clojure DSLs
Clojure
1,193
star
3

neil

A CLI to add common aliases and features to deps.edn-based projects
Clojure
288
star
4

scittle

Execute Clojure(Script) directly from browser script tags via SCI
Clojure
278
star
5

obb

Ad-hoc ClojureScript scripting of Mac applications via Apple's Open Scripting Architecture.
Clojure
240
star
6

process

Clojure library for shelling out / spawning sub-processes
Clojure
183
star
7

cli

Turn Clojure functions into CLIs!
Clojure
153
star
8

fs

File system utility library for Clojure
Clojure
139
star
9

babashka.curl

A This library is mostly replaced by https://github.com/babashka/http-client
Clojure
119
star
10

bbin

Install any Babashka script or project with one command
Clojure
115
star
11

pods

Pods support for JVM and babashka
Clojure
100
star
12

http-client

HTTP client for Clojure and Babashka built on java.net.http
Clojure
83
star
13

pod-registry

Pod manifests describe where pods can be downloaded, etc.
Clojure
82
star
14

babashka-sql-pods

Babashka pods for SQL databases
Clojure
72
star
15

pod-babashka-aws

Deprecated, use https://github.com/grzm/awyeah-api
Clojure
61
star
16

http-server

Serve static assets
Clojure
58
star
17

book

Babashka book
Clojure
55
star
18

babashka.nrepl

The nREPL server from babashka as a library, so it can be used from other SCI-based CLIs.
Clojure
52
star
19

pod-babashka-etaoin

Deprecated, use https://github.com/clj-commons/etaoin.
Clojure
41
star
20

tools-deps-native

Run tools.deps as a native binary
Clojure
40
star
21

pod-babashka-go-sqlite3

A babashka pod for interacting with sqlite3.
Go
27
star
22

pod-babashka-filewatcher

Babashka filewatcher pod based on Rust notify
Shell
22
star
23

json

JSON abstraction library
Clojure
19
star
24

pod-babashka-fswatcher

Babashka filewatcher pod.
Go
18
star
25

sci.configs

A collection of ready to be used SCI configs
Clojure
17
star
26

instaparse-bb

Use instaparse from babashka
Clojure
16
star
27

pod-babashka-buddy

A pod around buddy core (Cryptographic Api for Clojure).
Clojure
14
star
28

nbb-features

A collection of premade features for nbb
Clojure
10
star
29

toolbox

Script and template for Babashka Toolbox
HTML
9
star
30

pod-babashka-lanterna

Clojure
9
star
31

pod-babashka-malli

Exposing malli to babashka via a pod
Shell
8
star
32

nrepl-client

Clojure
8
star
33

pod-babashka-parcera

A babashka pod wrapping parcera
Clojure
7
star
34

conf

babashka-conf
Clojure
7
star
35

babashka.core

Babashka core utils
Clojure
5
star
36

pod-babashka-instaparse

Instaparse pod
Clojure
4
star
37

sci.nrepl

Clojure
2
star
38

babashka-dev-builds

2
star
39

.build

[INTERNAL] Common tooling for build orchestration
Clojure
1
star
40

babashka.github.io

Clojure
1
star
41

homebrew-brew

Ruby
1
star