qjs-modules
qjs-modules builds qjsm, a QuickJS-based
interpreter with both native C modules and JavaScript modules statically
linked in. The modules themselves provide the runtime APIs plain QuickJS
doesn't: console, fs, process, streams, sockets, XML/DOM, and more,
modeled on their Node.js/Bun/Deno/browser equivalents so scripts written
for those runtimes need few changes to run here. Some native modules wrap
existing C libraries (libarchive, libmagic, the MariaDB/MySQL client,
libpq, SQLite, libserialport, a bundled libbcrypt); the rest, and most of
the JavaScript modules, are original implementations or ports of existing
JavaScript libraries.
Every module can also be built standalone as a shared library and
imported at runtime by any QuickJS build, independent of qjsm. Each
quickjs-*.c file provides one native module.
Overview
qjsm— the interpreter binary this project builds (see qjsm below): QuickJS plus this project's modules statically linked in, so scripts getconsole,fs,process, and the rest without any setup.- Native C modules (
quickjs-*.c, Module index below) — one QuickJS module per file, documented indoc/native/. Some wrap third-party C libraries (libarchive, libmagic, MariaDB/MySQL, libpq, SQLite, libserialport); others are original C implementations. - JavaScript modules (
lib/*.js) — polyfills of standard APIs, higher-level wrappers over the native modules, and prototype extensions (Array,Map, …), documented indoc/js/. - Vendored C libraries (git submodules and bundled sources: libarchive, libbcrypt, libserialport, libutf, tutf8e) that some native modules build against or statically link.
- Sibling projects (
../qjs-lws,../qjs-glfw,../qjs-nanovg) — HTTP/WebSocket, windowing/GL, and 2D canvas support. Kept out of this repo so it stays installable on plain QuickJS without pulling in a network stack or a GPU-backed renderer; see Sibling Projects for why.
Building
cmake -B build .
make -C buildThe core modules are always built. Some modules depend on external libraries and are gated by CMake options:
| Option | Module | Dependency |
|---|---|---|
MODULE_ARCHIVE | archive | libarchive (BUILD_LIBARCHIVE builds the bundled one) |
MODULE_BCRYPT | bcrypt | bundled libbcrypt |
MODULE_MAGIC | magic | libmagic |
MODULE_MYSQL | mysql | MariaDB/MySQL client library |
MODULE_PGSQL | pgsql | libpq |
MODULE_SQLITE | sqlite | sqlite3 |
MODULE_SERIAL | serial | libserialport (BUILD_LIBSERIALPORT builds the bundled one) |
In addition to the native modules listed below, the lib/ directory
contains pure-JavaScript modules (console, fs, process, repl,
require, util, parsers, …) built on top of them; see
doc/js/.
Module index
| Module | Exports | Description |
|---|---|---|
| archive | Archive, ArchiveEntry, ArchiveMatch | Read/write archives via libarchive |
| arraybuffer_sink | ArrayBufferSink | Collect streamed writes into an ArrayBuffer |
| bcrypt | genSalt, hash, compare | bcrypt password hashing |
| bjson | read, write | Binary JSON (QuickJS object serialization) |
| blob | Blob | W3C-style binary blob |
| child_process | exec, spawn, ChildProcess, … | Spawn and control subprocesses |
| deep | find, get, set, iterate, … | Deep object-tree traversal and manipulation |
| directory | Directory | Low-level directory reader (getdents) |
| gpio | GPIO | Memory-mapped GPIO (Raspberry Pi) |
| inspect | inspect | Pretty-print JS values (like Node's util.inspect) |
| json | read, write, JsonParser | JSON parser/serializer with location info |
| lexer | Lexer, Token, Location | Regex-rule based tokenizer |
| list | List, ListIterator, ListNode | Doubly-linked list with Array-like API |
| location | Location | Source position (file:line:column) |
| magic | Magic | File type detection via libmagic |
| misc | many functions | Grab-bag of OS, buffer, type and engine utilities |
| mmap | mmap, munmap, … | Memory-mapped files as ArrayBuffers |
| mysql | MySQL, MySQLResult, MySQLError | Non-blocking (promise-based) MySQL/MariaDB client |
| path | join, basename, resolve, … | Path manipulation and filesystem tests |
| pgsql | PGconn, PGresult, PGerror | Non-blocking PostgreSQL client |
| pointer | Pointer, DereferenceError | Object-graph paths (JSON-pointer-like) |
| predicate | Predicate | Composable, callable predicate functions |
| queue | Queue | Chunked byte FIFO |
| repeater | Repeater | Push-to-async-iterator bridge |
| serial | Serial, SerialPort, SerialError | Serial ports via libserialport |
| sockets | Socket, AsyncSocket, SockAddr, … | BSD sockets, sync and async |
| sqlite | SQLite3, SQLite3Result, SQLite3Error | SQLite3 client |
| stream | ReadableStream, WritableStream, … | WHATWG-style streams |
| syscallerror | SyscallError | Error class carrying syscall name + errno |
| textcode | TextDecoder, TextEncoder | UTF-8/UTF-16/UTF-32 transcoding |
| tree_walker | TreeWalker, TreeIterator | DOM-TreeWalker-style object traversal |
| wasm | Module, Instance, Memory, Table, Global, … | WebAssembly JS API over wasm3 or WAMR |
| virtual | VirtualProperties | Uniform property access over Map/Array/Object |
| yaml | write | Block-YAML writer |
| xml | read, write | XML parser and serializer |
qjsm
qjsm is the interpreter binary this project builds: QuickJS
with a curated set of this project's modules statically linked in and
registered as builtins, so scripts can import them without any
dlopen()/module-path setup. Bare qjs (upstream QuickJS's own shell)
has none of this — only std/os, and only when passed --std. qjsm
also supports --std, but neither std nor os is loaded unless asked
for; nothing here auto-injects globals a script didn't request.
Which modules are builtins is controlled by CMake variables, set at configure time:
| Variable | Meaning | Default |
|---|---|---|
BUILTINS_COMPILED | Precompiled JS modules (bytecode) | assert console events fs module perf_hooks process repl timers tty url util |
BUILTINS_NATIVE | Native C modules linked in directly | path stream yaml |
BUILTINS_NATIVE_EXCLUDE | Native modules built but not registered as builtins (still importable via a .so, if BUILD_SHARED_MODULES built one) | arraybuffer-sink child-process lexer location repeater tree-walker virtual |
EXTERNAL_MODULES | Externally-built modules (e.g. from ../qjs-glfw) to link in, via <name>_MODULE | (empty) |
BUILTIN_MODULES | Convenience list: mixes module names and external-module build directories, auto-routed into the three variables above | (empty) |
BUILTINS_NATIVE's short default list isn't the full picture — any
builtin's own transitive module dependencies (e.g. stream needs
queue) are pulled in automatically by a dependency closure at
configure time, regardless of BUILTINS_NATIVE_EXCLUDE. CommonJS
require() (lib/require.js) is not a default builtin; add require
to BUILTINS_COMPILED to get it.
Every builtin module can still be built as a standalone .so and
imported at runtime instead of using the static build —
BUILD_SHARED_MODULES/BUILD_STATIC_MODULES (both ON by default)
build each module both ways independently. Static linking into qjsm
is the convenient default, not the only way to consume a module.