
Carne /kär-nē/ • a JavaScript runtime 👑 Written in Nim language
nimble install carne / clue install carne --build
Note
Carne is still experimental: it runs on macOS and Linux
(Linux needs libjavascriptcoregtk-4.1-dev installed), the std/* API
may change between 0.x releases, and a few modules are parse-only
in v1 (see the Standard Library notes below). Scripts needing
top-level await must wrap in an async IIFE for now. Not recommended
for production yet, but the full test suite passes on both platforms
and every example below is covered by it.
A JavaScript runtime based on JavaScriptCore and Nim! No drama, no overhype. With a rich
standard library, so you don't need npm anymore! Still, it ships with an efficient package manager that
abolishes node_modules and keeps dependencies in one shared global store instead.
Carne is not a drop-in replacement for Node.js, Bun or Deno, instead it is a runtime with an opinion: most scripts should not need a dependency at all. It trades the npm ocean for a standard library that covers everyday work out of the box, starts in ~8 ms on the back of JavaScriptCore, and stays ~6k lines of Nim, small enough to read in an afternoon. If you want the Node ecosystem, keep Node. If you want a script that just runs, take Carne.
- JavaScript runtime powered by JavaScriptCore
- Powerful Standard Library fully written in Nim lang
- Cryptographic library via pkg/nimcypher
- HTTP/1.1, H/2, UDP, TCP and WebSockets library via pkg/powpow
- Built-in formatters:
yaml,toml,csv,xml,markdown,vcard,feed,sql,css,diff,qr,svgvia pkg/openparser (colorsis pure JS) - Built-in archives and compression:
tar,zip,rar,gz,lz4,bz2,brotlivia pkg/archive - i18n via GNU Gettext PO/MO
- CSS and JavaScript bundler via pkg/squeezy
- Built-in database driver and ORM for sqlite and postgres, async + sync (
std/db) - Multi-worker HTTP serving off one port, with zero-copy file responses (sendfile, ETag/Range)
- Built-in test runner:
carne testdiscovers and runstests/**/*.test.js(std/test) - Native addons: Nim shared libraries (
.addon) with anewAddonauthor macro,carne buildandcarne gen addon(examples/addon/) - Terminal toolkit: styling, prompts, password reads, CLI arg parsing (
std/terminal) - Built-in package manager (
carne pkg)- one shared global store in your home dir, no
node_modules, no duplicated installs across projects install(by name or--url),remove,update,list,pruneorphans,refreshregistry datadevelop <path>for editable installs from a local directorypackage.jsonmanifests, npm-spec compliant; public registry at getcarne/carnepkgs
- one shared global store in your home dir, no
- Written in Nim language
- Open Source |
MITLicense
A JavaScript runtime in Nim
(c) OpenPeeps | MIT License
Build Version: 0.1.5
usage: carne <command> [args] [options]
Scripting:
run <script.js> [args] run a .js file (script args pass through verbatim)
test [file] [...] run tests/**/*.test.js (or the given file)
build <input.nim> <output> compile a native addon (.addon)
--release optimized build (-d:release)
Standard library:
std init download JS stdlib (std/*) into ~/.carne/std
std update refresh all JS stdlib files
std list show installed JS stdlib version and files
Packages:
pkg init [dir] scaffold a new package (wizard, -Y skips it)
--yes, -Y skip the wizard, use defaults
pkg install <spec> install a package by name, git URL, gh:user/repo alias, name#ref, or name + source URL
--url:<url> pin a source URL
pkg remove <name> [ver] uninstall one version, or all
--yes skip confirmation prompts
pkg update [name] update one package, or all
pkg list list installed packages
pkg develop [path] editable install from a local directory
pkg prune remove orphaned packages
--yes skip confirmation prompts
pkg refresh re-download registry data
pkg publish open a PR adding this package to the registry
--tags:<list> comma-separated tags
--web:<url> package website URL
--url:<url> pin a source URL
--dry-run no network, git, or secret changes
--yes skip confirmation prompts
Generating:
gen docs generate API reference into carnedocs/ (JSON and/or HTML)
--format:<json|html|all> docs output selection (default: all)
--out:<dir> docs output directory (default: carnedocs)
--entry:<file> document one file instead of the whole package
gen ast <file> dump the JavaScript AST of <file> (JSON or binary .ast)
--format:<json|bin> ast output selection (default: json)
--out:<dir> ast output directory (default: alongside the input)
gen addon <dir> scaffold a native addon project in <dir>
Versioning:
bump [semver] bump version in package.json (or a direct dep)
--level:<level> major, minor, or patch
--dep:<name> bump a direct dependency spec (prefix kept)
upgrade [version] self-update carne from GitHub releases (into ~/.carne/bin)
--dry-run print resolved URLs only, no changes
Inspect:
dump [pkg[@ref]] print package.json (cwd or an installed package)
options:
--isatty:<true|false> override TTY detection (default: auto-detect)
-h, --help show this help
--version show version
A DFS (depth-first search) package manager with one shared global store
(~/.carne, no node_modules), built on
pkg/datpkgr, the same engine used
at tim,
clue,
bowdy. It installs from both git
and npm-style sources:
carne pkg install <git-url>(or--url=...to pin a source URL):https://URLs,git+/git://transports,git@and.gitURLs, plus forge aliases (gh:user/repo, long formgithub:; alsogl:,cb:,srht:). A#refsuffix pins a branch or tag:carne pkg install gh:user/repo#v1. Works today.- The cloned repo must contain a valid
package.jsonat its root; anything else is rejected, not installed. carne pkg install <name>[@range],npm:name@rangealiases: resolved through the package registry at getcarne/carnepkgs (sourcecarne, cached at~/.carne/registries/carne.json;carne pkg refreshre-downloads it).carne pkg develop [path]: editable installs from a local directory (default: current dir).remove,update,list,prune,refreshmanage the store.carne bump [semver] [--level=major|minor|patch] [--dep=name]: bumps the version in the localpackage.json(default: patch; explicit semver sets it). With--dep=nameit bumps that direct dependency's spec instead (dependencies,devDependencies,optionalDependencies,peerDependencies), keeping the range prefix (^0.1.0patch-bumps to^0.1.1). Only the bumped value changes; formatting is preserved.carne upgrade [version]: self-updates from getcarne/carne releases into~/.carne/bin(created on first use; add it toPATH). Bare takes the latest release, a version pins one (0.1.3orv0.1.3);--dry-runprints the URL only. The previous binary is kept ascarne.prev.<old>.carne dump [pkg[@ref]]: prints the rawpackage.json— the one found from the cwd upwards, or an installed package's (develop checkouts included).carne pkg publish [--tags=..] [--web=..] [--url=..] [--dry-run] [--yes]: opens a pull request adding the current package to getcarne/carnepkgs (fork, insert intopackages.jsonin name order, PR againstmain).description,licenseandkeywords(registry tags) are required inpackage.json; the repo URL comes from.git/config(remote.origin.url). Auth is the GitHub token on its own line in~/.carne/.tokens(chmod 600).--dry-runprints the entry without touching the network.
Installed packages load through require("pkg/<name>") as CommonJS:
entry resolution reads the exports map root first, then main
(index.js, src/index.js, <name>.js fallbacks). A @version
suffix pins an installed version, pkg/<name>/sub/path reaches
inside, and ./... requires work between package files (and from
carne run scripts, relative to the script).
const demo = require("pkg/carne_demo_pkg");
console.log(demo.hello("ada")); // hi adaA @version suffix pins an installed version
(require("pkg/greet@0.1.0")), and pkg/<name>/sub/path reaches
inside a package.
Only CommonJS v1: ESM (import/export) packages fail with a clear
error, as do packages with no loadable entry.
Nim shared libraries (.addon) callable from JS, Node-addon style:
a package wraps a prebuilt binary with a JS entry that requires it
relatively. Authors write newAddon from carne/api/addon (same
registerFn types and arity checks as std modules), compile with
carne build, and ship the binary beside the wrapper:
import carne/api/addon
newAddon("hello", "0.1.0"):
exportObject:
registerFn hello(name: default(string, "world")):
## hello([name]) -> greeting string
return toJS(ctx, "Hello, " & name & "!")// index.js — the wrapper: scalar type checking lives at the native
// boundary (wrong types throw TypeError), so it only adapts shapes
// and composes behavior.
const native = require("./native/hello.addon");
module.exports = { hello: native.hello };carne gen addon hello # scaffold a wrapper package
carne build native/hello.nim native/hello.addonBuilding requires carne as a Nim package, via nimble or clue.
require("./x.addon") works from any JS file (package or script);
one library loads per process with fresh exports per context, and
the loader major-matches the addon against the host carne. See
examples/addon/ for the full wrapper pattern.
All modules load lazily via the global require("std/<name>"),
requiring one costs nothing until first use. Timers are globals
(No require needed), Node-style.
The library covers OS and process access, data formats, text processing, crypto, networking, and developer tools:
std/env- process info and environment (args, getEnv, putEnv, delEnv, hasEnv, parse/load.env, cwd, exit)std/os- synchronous OS utilities (files, dirs, exec)std/archive- archive creation/extraction and compression (tar, zip, rar, gz, lz4, bz2, brotli)- Timers -
setTimeout/setInterval/sleepglobals, no require needed std/yaml- YAML parsing and serializationstd/toml- TOML parsing and serializationstd/ical- iCalendar parsing and serializationstd/plist- Apple property listsstd/bson- BSON parsing and serializationstd/csv- CSV parsingstd/xml- XML parsing and serializationstd/html- HTML parsing (parse-only in v1)std/vcard- vCard contact parsing (parse-only in v1)std/feed- RSS and Atom feed parsing (parse-only in v1)std/sql- SQL parsing and validation (sqlite, postgres, mysql)std/crypto- hashing, AEAD/XChaCha20-Poly1305 + AES-GCM sealing, ed25519/X25519, ECDSA/ECDH, RSA, passwordsstd/path- file-path and URL parsing (parse-only in v1)std/colors- color parsing, formatting and math (fetched viacarne std init)std/css- CSS parsing and declaration validationstd/diff- unified diffsstd/gettext-.poparsing and translation,.mofile catalogsstd/str- string utilities and validators (fetched viacarne std init)std/mimetype- MIME type lookupstd/benchmark- in-process microbenchmarkingstd/qr- QR code generation (model2/model1/micro/rmqr/aqr/sqrc), matrix decoding, payload buildersstd/svg- SVG parsing and serializationstd/http- async HTTP client + server (optional worker threads)std/ws- async + sync WebSocket client and serverstd/tcp- async TCP client + server, optional TLSstd/udp- async UDP sockets (bind/connect, rinfo echo)std/uuid- UUID generation (v1-v8) and inspectionstd/nanoid- URL-friendly id generationstd/url- URL parsing and formattingstd/watcher- file watching (async watch + sync watchOnce)std/terminal- terminal styling, size, raw output, reads, CLI arg parsingstd/test- minimal test runner (test/describe/expect/assert, fetched viacarne std init)std/db- async + sync database driver and ORM (sqlite, postgres, fetched viacarne std init)
Full API reference with examples: https://openpeeps.github.io/carne/
- JSC runtime: console/process/require/timers CLI
- Package management (
carne pkg, manifests) - Format std libs (yaml, toml, ical, env, plist, bson, csv, xml, vcard, feed)
-
std/sql,std/crypto,std/path,std/colors -
std/css,std/diff,std/gettext,std/mimetype,std/benchmark,std/qr,std/svg -
std/http(async client + server, tuning opts, method helpers) + top-level promise unwrap inrunCode -
std/ws(async + sync client, server, binary/ping/protocol,wss://client) -
std/httpworkers (cluster-style threads,process.isWorker) -
std/uuid(v1-v8 generation, parse/inspect, RFC namespace constants) -
std/db(async + sync driver, fluent builder, models, migrations; sqlite + postgres) -
std/archive(tar/zip/rar creation + extraction, gz/lz4/bz2/brotli; in-memory and file APIs) - Lazy startup (deferred event loop, per-run TLS, cached spec data)
- Benchmark suite + results
- Top-level await in scripts (currently needs an async IIFE)
-
std/crypto: X25519 exchange, RSA/ECDSA, AES-GCM -
std/gettext.mofile catalogs,std/svgstringify (std/qrdecode deferred) -
exportClassin the module DSL - Public package registry (getcarne/carnepkgs)
-
carne pkg publish(fork + PR flow,.tokensauth) - Beyond macOS (Linux via JavaScriptCoreGTK 4.1)
Kinda useless JS bench suite (bench/js, via hyperfine --warmup 2 --min-runs 3,
macOS, bench/run.sh reproduces; node v22.22.1, bun 1.4.3):
| Benchmark | carne | node | bun |
|---|---|---|---|
| fib_recursive | 42.4 ms ± 0.5 ms | 85.1 ms ± 1.1 ms | 45.5 ms ± 1.0 ms |
| nested_loops | 9.3 ms ± 0.4 ms | 36.3 ms ± 0.7 ms | 11.9 ms ± 0.4 ms |
| prime_sieve | 9.2 ms ± 0.3 ms | 35.0 ms ± 0.5 ms | 11.7 ms ± 0.3 ms |
| string_concat | 9.4 ms ± 0.3 ms | 34.5 ms ± 0.5 ms | 11.7 ms ± 0.7 ms |
| tail_recursive | 9.7 ms ± 0.3 ms | CRASHED | 11.8 ms ± 0.3 ms |
| range_sum | 38.4 ms ± 0.4 ms | 43.8 ms ± 0.4 ms | 19.6 ms ± 0.3 ms |
| collatz | 51.1 ms ± 0.4 ms | 69.5 ms ± 0.7 ms | 53.4 ms ± 2.3 ms |
| array_sum | 14.6 ms ± 0.5 ms | 40.7 ms ± 0.9 ms | 16.8 ms ± 0.3 ms |
| bubble_sort | 11.8 ms ± 0.3 ms | 36.7 ms ± 0.4 ms | 14.5 ms ± 0.3 ms |
| object_access | 11.3 ms ± 0.3 ms | 36.9 ms ± 0.4 ms | 14.0 ms ± 0.3 ms |
| float_math | 12.9 ms ± 0.3 ms | 39.1 ms ± 1.0 ms | 16.5 ms ± 0.4 ms |
| call_overhead | 10.4 ms ± 0.2 ms | 35.5 ms ± 0.4 ms | 12.5 ms ± 0.3 ms |
| fizzbuzz_count | 43.8 ms ± 0.4 ms | 64.8 ms ± 0.6 ms | 38.3 ms ± 0.4 ms |
A cold hello.js run costs carne ~8.5 ms, so everything near that floor is
startup-dominated (JSC context + stdlib install), not compute. Node crashes
tail_recursive (no proper tail calls: stack overflow at 10k frames);
carne inherits JSC's tail-call support, like bun.
Throughput bench (bench/http-hello, bench/http-hello/run.sh reproduces;
wrk 4.2.0, wrk -t4 -c100 -d10s after a 2s warmup, port 3000, macOS,
node v22.22.1, bun 1.4.4). Each server answers 200 text/plain "hello world" to every request; carne-workers is the same server
with {workers: 4} (bench/http-hello/server.carne.workers.js):
| Runtime | Requests/sec | Avg latency | Max RSS |
|---|---|---|---|
| carne | 91330.44 | 1.15ms | 10.9 MB |
| carne-workers | 144029.68 | 739.70us | 28.3 MB |
| node | 38576.69 | 2.71ms | 61.5 MB |
| bun | 86878.46 | 1.15ms | 31.1 MB |
Bodies are byte-identical (11 bytes); headers differ per runtime, so
Transfer/sec is not directly comparable. Max RSS is sampled via
ps during the measured run (includes shared libraries).
- 🐛 Found a bug? Create a new Issue
- 👋 Wanna help? Fork it!
MIT license. Made by Humans from OpenPeeps.
Copyright OpenPeeps & Contributors — All rights reserved.