Opal is an all-in-one toolkit for JavaScript and TypeScript projects, built to cover package management, running code, bundling, and testing. It ships as a single executable called opal.
At its core is opal-core, a module graph engine written in Rust. It works out what every file imports and where each import resolves, then caches that answer by content hash, so the next run over unchanged files is a cache hit. Every tool Opal adds is meant to share that one graph instead of carrying its own resolver.
The first of those tools is the package manager, and it works today. It picks the versions npm would, with a few documented differences, lays out node_modules the way npm does, and links every file in from a single content-addressed store shared by all the projects on your machine.
opal install # install the dependencies in package.json
opal add express # add a dependency (also: opal install express)
opal add -D typescript@^5 # add a devDependency at a range you choose
opal remove express # remove oneThe opal command-line tool also lets you inspect a project's module graph and the shared store. Installs are crash-safe: if one is killed partway through, running opal install again finishes the job.
opal graph index.js --root . # resolve everything index.js imports
opal cache verify # re-hash the shared store and check it for corruption
opal cache gc # delete store files no project uses anymoreStatus: Beta. The package manager works today —
opal installresolves against the real npm registry and produces anode_modulestree Node runs against, validated on real projects (a Next.js scaffold at 365 packages, express, webpack, and a curated compatibility suite), and it is under active development, so expect rough edges and breaking releases.opal runruns package.json scripts andopal xruns package commands, both checked against npm's. The bundler (opal build) is new and deliberately narrow: see Bundling. Running a JavaScript or TypeScript file (opal run app.js) is new too, and covers part of Node's API so far: see Running files. The test runner (opal test) is not implemented; its directory undercrates/holds placeholder files only.
Opal supports Linux (x64 & arm64) and macOS (x64 & Apple Silicon). On Windows, it runs inside WSL2.
Linux users: the prebuilt binaries need glibc 2.34 or newer (Ubuntu 22.04+, Debian 12+, Fedora 35+, RHEL 9+). Check yours with
ldd --version. v0.3.1 is the exception: it needs glibc 2.39 (Ubuntu 24.04+, Debian 13+, Fedora 40+). On an older system, the install script stops without installing anything. Alpine and other musl-based distributions aren't supported.
Windows users: install and run Opal inside WSL2. Native Windows support is planned.
# with install script (recommended)
curl -fsSL https://opalx.dev/install.sh | bash
# a specific version
curl -fsSL https://opalx.dev/install.sh | OPAL_VERSION=v0.3.0 bash
# from source (prerequisites are in CONTRIBUTING.md)
git clone https://github.com/saintparish4/opal && cd opal
cargo build --release # binary at ./target/release/opalInstalling with npm or Homebrew is planned. Until then, use the install script.
The script picks the binary for your OS and CPU from the GitHub Release, verifies its SHA256 checksum, and installs it to ~/.opal/bin/opal. It puts that directory on your PATH by adding one line, marked # added by opal's install.sh, to ~/.zshrc, ~/.bashrc, or ~/.profile. To uninstall, delete the directory opal cache path prints, then ~/.opal and that line.
Opal is pre-1.0 beta software, and the lockfile format can change between minor versions. Don't point it at a project you can't reinstall.
To upgrade to the latest version of Opal, run:
opal upgradeTo switch to a specific version, older or newer, name it:
opal upgrade 0.3.1It downloads the release for your platform from GitHub, checks it against the release's SHA256SUMS, and runs it once to make sure it starts before replacing the binary, so a failed upgrade leaves the old one untouched. Running the install script again works too.
If the new version changed the lockfile format, the next opal install in each project re-resolves opal.lock and says so. Commit the rewritten file, because opal install --frozen-lockfile refuses to rewrite it and CI fails until you do. An older Opal can't read a lockfile written by a newer one.
There's no canary channel; every release is a tagged GitHub Release, and what changed in each is in CHANGELOG.md. To run unreleased changes from master, build from source.
Opal has nine commands today: opal install, opal add, opal remove, opal run, opal x, opal build, opal graph, opal cache, and opal upgrade. Run opal <command> --help to see their flags.
Commit opal.lock. In CI, run opal install --frozen-lockfile, which installs exactly what opal.lock records and fails instead of changing it.
opal add <package> writes the dependency to package.json, updates opal.lock, and installs it. opal install <package> does the same thing. opal remove <package> (or opal rm) takes it out of every dependency group and out of node_modules.
opal add express # the latest release, saved as a ^ range on it
opal add express@4.21.2 # a version you typed is saved as typed: 4.21.2
opal add 'express@^4.0.0' # and so is a range: ^4.0.0
opal add -D vitest # devDependencies (-O for optionalDependencies)
opal add -E zod # the exact version instead of a ^ range
opal add old-ms@npm:ms@^2.0.0 # an alias- Only what you name moves. Every other package keeps the version in
opal.lock, even when the registry has something newer. The same holds after you editpackage.jsonby hand and runopal install. - A package you name gets what the registry has now, and anything else that depends on it moves to that same version when its range allows, so you don't end up with two copies.
package.jsonkeeps its formatting. Indentation, line endings, key order, and everything outside the dependency group being edited are written back as they were. The edited group is sorted by name.- Nothing is written unless the change resolves. A mistyped package name or a range nothing satisfies leaves
package.jsonandopal.lockuntouched. So doesopal removeof a name that isn't a dependency, which is an error and not a silent success. - To re-resolve everything from scratch, delete
opal.lockand runopal install.
Not supported yet, and planned for v0.5.0: --peer, --global, git: and file: specifiers, and opal add in a directory that has no package.json.
opal run # list package.json's scripts
opal run build # prebuild, build, postbuild, as npm runs them
opal run test --watch # everything after the name is the script's
opal x tsc --noEmit # a command from node_modules/.bin
opal x cowsay@1.6.0 hello # installed once into the cache, then runopal run follows npm's own source (@npmcli/run-script): the script runs in the project folder with every node_modules/.bin from there up on PATH, sees the npm_package_* and npm_lifecycle_* variables tools read, and ends opal with its own exit code or signal. Where it differs: npm's own settings (npm_config_cache and the like) aren't exported, the shell is /bin/sh (npm's script-shell isn't read), workspaces aren't supported, and flags after the script's name are the script's, where npm would read them as its own.
opal x installs a package the first time it's asked for and reuses that install after, so a range or tag (cowsay, cowsay@latest) is resolved once, not on every run.
update, why, outdated, audit, and publish aren't implemented yet, so the binary doesn't have them. A command that exists and does nothing is worse than one that doesn't exist.
opal run runs a JavaScript or TypeScript file on an embedded V8, the way Node 24 runs it.
opal run app.js # CommonJS or an ES module, as Node decides
opal run script.ts --verbose # types stripped as Node 24 strips them; arguments go to the script
opal run ./bin/tool # a name with a `/` in it is a file, not a scriptIt aims to be exact rather than complete. Most of what a program reaches is Node's own library code, copied unmodified from Node 24.19.0: util.inspect, events, path, buffer, fs, assert, timers, and the error messages and codes, over native code that does what Node's C++ does. So console.log of any object, a failed readFileSync, and an uncaught error print what Node prints, byte for byte.
What it does: CommonJS, ES modules and JSON with Node's resolution, require() of an ES module, import(), import.meta, top-level await, TypeScript files (.ts, .mts, .cts), console, process (argv, env, exit codes, nextTick, warnings, uncaughtException), path, Buffer, events, util (in part), every fs function in its synchronous, callback and promise forms (FileHandle, fs.opendir and fs's streams included), stream, os, string_decoder, async_hooks (AsyncLocalStorage), AbortController and EventTarget, assert, and timers (timers/promises too).
What it doesn't do yet: fs.watch, web streams, child_process, net and http, worker_threads, crypto, url, and Node's command-line flags. Requiring one of those fails with an error that says Opal doesn't implement it yet, rather than with something that half works.
How it is checked: nine corpora (inspect, buffer, fs in each of its three forms, streams, os, modules, ES modules) are run under opal run and under node 24.19.0 in CI and must print the same bytes; the TypeScript stripper matches Node's on 18,522 real-world files, and resolution matches Node's on 198,352 generated cases. Node's own tests for these areas run unmodified through compat/node-tests.py: 557 of 873 pass today, file by file in compat/NODE-TESTS.md, with the reason each other one fails.
How fast it starts: a script that loads fs, path, util, assert and events starts in 18.0 ms here, as fast as bun (0.99×) and half node's time; opal run hello.js, which loads none of Node's library, takes 12.7 ms, against 6.6 ms for bun and 36.1 ms for node. Both are measured by benchmarks/compare-runtimes.py. Node's shared internals are in the startup snapshot, which makes the first faster and the second slower; starting faster than bun is the goal, and not met for hello yet.
opal build bundles an entry file and everything it imports into one ES module, with a source map, from the same module graph opal graph prints.
opal build src/main.ts # writes dist/main.mjs and dist/main.mjs.map
opal build src/main.ts --target browser # resolves with the browser condition
opal build src/main.ts --external react # keeps a package out of the bundle
opal build src/main.ts --define process.env.NODE_ENV='"production"'
opal build src/main.ts --why node_modules/ms/index.js # the import chain that pulls a module in
opal build src/main.tsx --target browser --assets # images and stylesheets, as Vite imports themIt aims to be small and exact rather than complete. A bundle has to be indistinguishable from the unbundled program when Node runs it: same output, same exit code, same uncaught error, same evaluation order, same .name on every function and class, same CommonJS and JSON semantics. The contract is crates/opal-bundler/SEMANTICS.md, with every rule's ECMA-262 clause or Node source line. Where the bundler cannot keep a rule, it refuses with a code (E-TLA, E-LINK, …) that names the module and line, instead of writing a bundle that might behave differently.
What it does: ES modules and CommonJS in any mix, cycles, live bindings, dynamic import(), TypeScript and JSX compiled as tsc compiles them, JSON, import.meta, Node builtins, externals, --define, and tree shaking of declarations that provably do nothing.
What it refuses, on purpose: top-level await outside the entry module, require() of an ES module, direct eval in an ES module, non-JavaScript imports unless --assets is given, and output formats other than ES modules. Code splitting, plugins, minification, CSS processing, and HTML entry points are out of scope.
How it is checked: every test fixture runs unbundled and bundled under Node and the two runs are compared; generated module graphs are fuzzed the same way, 157,547 programs in the last two-hour run with none diverging (fuzzing); test262's module tests run through it (results); esbuild and rollup are held to the same Node runs of the same fixtures (results); the CommonJS export lexer is a port of Node's own, checked against Node on 20,998 files from npm, the compat starters' dependencies; and the Nest, Express, and vite-react starters run from their bundles in the compatibility matrix.
How fast it is: on esbuild's three.js benchmark (3,701 files), a rebuild with the module graph cached takes 654 ms, against 708 ms for esbuild and 418 ms for bun, and a build from nothing takes 867 ms. The method and every number are in benchmarks/BENCHMARKS.md.
Opal 0.4.0 against npm, pnpm, yarn, and bun, each installing the same package.json. Measured 2026-10-06 with benchmarks/compare-pms.py and the release binary. Four of its six scenarios are shown here:
- cold: no lockfile, cache, or
node_modules(a first install) - ci: a lockfile, but no cache or
node_modules(a fresh CI runner) - warm: a lockfile and a cache, but no
node_modules(a reinstall on your machine) - noop: everything already installed
Each number is the median of 3 runs (cold, ci) or 5 (warm, noop); fastest in bold. Every tool gets its own copy of the project and its own empty cache, the tools take turns so a network swing hits all of them, and install scripts are off for all five. Machine: AMD Ryzen 5 5625U (WSL limited to 8 of 12 threads), 16 GB RAM, Linux under WSL2, Node 24.19.0.
express (68 packages)
| cold | ci | warm | noop | Peak memory (cold) | |
|---|---|---|---|---|---|
| opal 0.4.0 | 913ms | 491ms | 92ms | 16ms | 33 MB |
| npm 12.0.2 | 1.75s | 1.04s | 643ms | 389ms | 160 MB |
| pnpm 11.21.0 | 1.36s | 1.23s | 765ms | 470ms | 329 MB |
| yarn 1.22.22 | 1.55s | 1.22s | 552ms | 266ms | 161 MB |
| bun 1.4.2 | 1.35s | 175ms | 67ms | 6ms | 26 MB |
Next.js 16.3.2, the create-next-app defaults (about 360 packages)
| cold | ci | warm | noop | Peak memory (cold) | |
|---|---|---|---|---|---|
| opal 0.4.0 | 24.06s | 18.84s | 907ms | 72ms | 491 MB |
| npm 12.0.2 | 27.58s | 13.43s | 10.85s | 633ms | 464 MB |
| pnpm 11.21.0 | 19.29s | 16.07s | 2.25s | 490ms | 1,794 MB |
| yarn 1.22.22 | 53.40s | 47.05s | 5.41s | 352ms | 659 MB |
| bun 1.4.2 | 17.27s | 11.99s | 1.09s | 16ms | 216 MB |
Across both machines (the second is an Intel Core i9-9900K, 16 threads):
- Reinstalls are where it wins. A warm install is 7× faster than npm on express and 12–19× on Next.js, where it is ahead of bun on one machine and level with it on the other. A no-op install is 20–24× (express) and 9× (Next.js) faster than npm; bun is faster still.
- A first install of a large app is faster than npm's and slower than pnpm's and bun's. On Next.js, Opal's cold install is 1.1–1.2× faster than npm's, and their ranges don't overlap on either machine; pnpm is 1.2–1.3× faster than Opal and bun 1.4–1.5×. On express, Opal is ahead of npm, pnpm, and yarn, and three runs don't separate it from bun.
- CI on a large app is where it loses. With a lockfile and an empty cache, Opal is 1.3–1.4× slower than npm on Next.js, 1.2–1.3× slower than pnpm, and 1.6× slower than bun. Nearly all of that install is the download. v0.3.0, which downloaded one package at a time, was 6–13× slower than npm on this install.
- Memory: bun uses the least on both projects. Opal is second on express and close to npm on Next.js.
- On Next.js, opal, yarn, and bun also download six musl builds that npm and pnpm skip (see Limitations), which adds to their cold and CI times.
Absolute times vary between sessions and machines, so compare tools within one table rather than across tables.
The full method, min–max ranges, the second machine's tables, the other two scenarios (CI with a restored cache, adding a package), disk usage, earlier releases' tables, and how to reproduce every number are in benchmarks/BENCHMARKS.md.
Worth knowing before you point Opal at a project:
- CI installs of a large app are slower than npm's: 1.3–1.4× on a Next.js app with a lockfile and an empty cache in the benchmarks. Downloads run 16 at a time since v0.4.0, and the download is still nearly all of that install.
opal addandopal removewith nothing cached ask the registry about every package in the tree, not only the one being changed. On a Next.js app (418 package names) that takes 5–7s, as on a machine that installed from a lockfile; npm takes under a second. With metadata cached, however old, an add takes about half a second.- Lifecycle scripts (
preinstall/install/postinstall) do not run. Packages shipping prebuilt binaries (esbuild,sharp,@next/swc) work; a package that needsnode-gypto compile at install time installs but does not build.opal installsays so on every run: it names each dependency whose install scripts were skipped (including native addons that declare none and rely on npm runningnode-gyp rebuildfor theirbinding.gyp), and the project's own lifecycle scripts,prepareincluded. libcisn't checked. On Linux with glibc (most distributions), Opal also installs the musl builds of native packages, which npm and pnpm skip. On a Next.js app that's six extra packages and 124 MB, 91 MB of it@next/swc-linux-x64-musl. A glibc system doesn't use them, but they cost download time and disk.- Peers are recorded and classified, never auto-installed.
opal buildrefuses more than other bundlers. It refuses what it cannot bundle exactly (see Bundling). The bundle reads its own location to find the original files' paths for__filename,import.meta.url, and runtimerequire(), so keep it next to the project it was built from.- Versions can differ slightly from npm's. Opal reuses a version already in the tree whenever it satisfies a range, where npm sometimes adds a newer copy: on a Next.js app, that's one package (
postcss8.5.23, where npm also installs 8.5.28). Opal doesn't prefer versions whoseenginesmatch your Node, which npm does. And it doesn't honorbundleDependencies: packages a dependency ships inside its own tarball are also resolved and downloaded from the registry, though Node still loads the bundled copy. package-lock.jsonis ignored. In a project npm already installed, the firstopal installresolves every version and downloads every package again.git:andfile:specifiers are unsupported and reported as such; dependencies come from a registry only.- If your project and cache sit on different filesystems (a project on
/mnt/cunder WSL2 with the default cache, for instance), every file is copied instead of hardlinked and the install warns. Keep both on the same filesystem, or setOPAL_CACHE_DIRto a directory on the project's filesystem to move the shared store there.
See CONTRIBUTING.md to build Opal from source, run the tests, and check a change before opening a pull request.
MIT — see LICENSE.