Small and modular JavaScript runtime for desktop and mobile. Like Node.js, it provides an asynchronous, event-driven architecture for writing applications in the lingua franca of modern software. Unlike Node.js, it makes embedding and cross-device support core use cases, aiming to run just as well on your phone as on your laptop. The result is a runtime ideal for networked, peer-to-peer applications that can run on a wide selection of hardware.
npm i -g barebare [flags] <filename> [...args]
Evaluate a script or start a REPL session if no script is provided.
Arguments:
<filename> The name of a script to evaluate
[...args] Additional arguments made available to the script
Flags:
--version|-v Print the Bare version
--eval|-e <script> Evaluate an inline script
--print|-p <script> Evaluate an inline script and print the result
--inspect Activate the inspector
--help|-h Show helpThe specified <script> or <filename> is run using Module.load(). For more information on the module system and the supported formats, see https://github.com/holepunchto/bare-module.
Bare is built on top of https://github.com/holepunchto/libjs, which provides low-level bindings to V8 in an engine independent manner, and https://github.com/libuv/libuv, which provides an asynchronous I/O event loop. Bare itself only adds a few missing pieces on top to support a wider ecosystem of modules:
- A module system supporting both CJS and ESM with bidirectional interoperability between the two.
- A native addon system supporting both statically and dynamically linked addons.
- Light-weight thread support with synchronous joins and shared array buffer support.
Everything else if left to userland modules to implement using these primitives, keeping the runtime itself succinct and bare. By abstracting over both the underlying JavaScript engine using libjs and platform I/O operations using libuv, Bare allows module authors to implement native addons that can run on any JavaScript engine that implements the libjs ABI and any system that libuv supports.
The core JavaScript API of Bare is available through the global Bare namespace.
The identifier of the operating system for which Bare was compiled. The possible values are android, darwin, ios, linux, and win32.
The identifier of the processor architecture for which Bare was compiled. The possible values are arm, arm64, ia32, mips, mipsel, and x64.
Whether or not Bare was compiled for a simulator.
The command line arguments passed to the process when launched.
The ID of the current process.
The code that will be returned once the process exits. If the process is exited using Bare.exit() without specifying a code, Bare.exitCode is used.
Whether or not the process is currently suspended.
Whether or not the process is currently exiting.
The Bare version string.
An object containing the version strings of Bare and its dependencies.
Immediately terminate the process or current thread with an exit status of code which defaults to Bare.exitCode.
Suspend the process and all threads. This will emit a suspend event signalling that all work should stop immediately. When all work has stopped and the process would otherwise exit, an idle event will be emitted. If the process is not resumed from an idle event listener, the loop will block until the process is resumed.
Immediately suspend the event loop and trigger the idle event.
Resume the process and all threads after suspension. This can be used to cancel suspension after the suspend event has been emitted and up until all idle event listeners have run.
Emitted when a JavaScript exception is thrown within an execution context without being caught by any exception handlers within that execution context. By default, uncaught exceptions are printed to stderr and the processes aborted. Adding an event listener for the uncaughtException event overrides the default behavior.
Emitted when a JavaScript promise is rejected within an execution context without that rejection being handled within that execution context. By default, unhandled rejections are printed to stderr and the process aborted. Adding an event listener for the unhandledRejection event overrides the default behavior.
Emitted when the loop runs out of work and before the process or current thread exits. This provides a chance to schedule additional work and keep the process from exiting. If additional work is scheduled, beforeExit will be emitted again once the loop runs out of work.
If the process is exited explicitly, such as by calling Bare.exit() or as the result of an uncaught exception, the beforeExit event will not be emitted.
Emitted before the process or current thread terminates. Additional work must not be scheduled from an exit event listener. If the process is forcefully terminated from an exit event listener, the remaining listeners will not run.
Emitted after the process or current thread has terminated and before the JavaScript environment is torn down. Additional work must not be scheduled from a teardown event listener. Bare itself will register teardown event listeners to join dangling threads and unload native addons.
Important
teardown listeners SHOULD be prepended to have the listeners run in last in, first out order:
Bare.prependListener('teardown', () => { ... })Emitted when the process or current thread is suspended. Any in-progress or outstanding work, such as network activity or file system access, should be deferred, cancelled, or paused when the suspend event is emitted and no additional work should be scheduled.
Emitted when the process or current thread becomes idle after suspension. After all handlers have run, the event loop will block and no additional work be performed until the process is resumed. An idle event listener may call Bare.resume() to cancel the suspension.
Emitted when the process or current thread resumes after suspension. Deferred and paused work should be continued when the resume event is emitted and new work may again be scheduled.
stateDiagram
direction LR
[*] --> Active
Active --> Suspended: Bare.suspend()
Active --> Terminated: Bare.exit()
Active --> Exited
Suspended --> Active: Bare.resume()
Suspended --> Sleeping: Bare.idle()
Suspended --> Terminated: Bare.exit()
Suspended --> Idle
Idle --> Active: Bare.resume()
Idle --> Terminated: Bare.exit()
Idle --> Sleeping
Sleeping --> Active
Terminated --> Exited
Exited --> [*]
The Bare.Addon namespace provides support for loading native addons, which are typically written in C/C++ and distributed as shared libraries.
Load a static or dynamic native addon identified by url. If url is not a static native addon, Bare will instead look for a matching dynamic object library.
Options are reserved.
Unload a dynamic native addon identified by url. If the function returns true, the addon was unloaded from memory. If it instead returns false, the addon is still in use by one or more threads and will only be unloaded from memory when those threads either exit or explicitly unload the addon.
Options are reserved.
Resolve a native addon specifier by searching for a static native addon or dynamic object library matching specifier imported from parentURL.
Options are reserved.
The Bare.Thread provides support for lightweight threads. Threads are similar to workers in Node.js, but provide only minimal API surface for creating and joining threads.
true if the current thread is the main thread.
A reference to the current thread as a ThreadProxy object. Will be null on the main thread.
A copy of or, if shared, reference to the data buffer that was passed to the current thread on creation. Will be null if no buffer was passed.
Start a new thread that will run the contents of filename. If callback is provided, its function body will be treated as the contents of filename and invoked on the new thread with Thread.self.data passed as an argument.
Options include:
{
// Optional data to pass to the thread
data: null,
// Optional file source, will be read from `filename` if neither `source` nor `callback` are provided
source: string | Buffer,
// Optional source encoding if `source` is a string
encoding: 'utf8',
// Optional stack size in bytes, pass 0 for default
stackSize: 0
}Convenience method for the new Thread() constructor
Whether or not the thread has been joined with the current thread.
Block and wait for the thread to exit.
Suspend the thread. Equivalent to calling Bare.suspend() from within the thread.
Resume the thread. Equivalent to calling Bare.resume() from within the thread.
Bare can easily be embedded using the C API defined in include/bare.h:
#include <bare.h>
#include <uv.h>
bare_t *bare;
bare_setup(uv_default_loop(), platform, &env /* Optional */, argc, argv, options, &bare);
bare_load(bare, filename, source, &module /* Optional */);
bare_run(bare);
int exit_code;
bare_teardown(bare, &exit_code);If source is NULL, the contents of filename will instead be read at runtime. For examples of how to embed Bare on mobile platforms, see https://github.com/holepunchto/bare-android and https://github.com/holepunchto/bare-ios.
Bare provides a mechanism for implementing process suspension, which is needed for platforms with strict application lifecycle constraints, such as mobile platforms. When suspended, a suspend event will be emitted on the Bare namespace. Then, when the loop has no work left and would otherwise exit, an idle event will be emitted and the loop blocked, keeping it from exiting. When the process is later resumed, a resume event will be emitted and the loop unblocked, allowing it to exit when no work is left.
The suspension API is available through bare_suspend() and bare_resume() from C and Bare.suspend() and Bare.resume() from JavaScript.
https://github.com/holepunchto/bare-make is used for compiling Bare. Start by installing the tool globally:
npm i -g bare-makeNext, install the required build and runtime dependencies:
npm iThen, generate the build system:
bare-make generateThis only has to be run once per repository checkout. When updating bare-make or your compiler toolchain it might also be necessary to regenerate the build system. To do so, run the command again with the --no-cache flag set to disregard the existing build system cache:
bare-make generate --no-cacheWith a build system generated, Bare can be compiled:
bare-make buildWhen completed, the bare(.exe) binary will be available in the build/bin directory and the libbare.(a|lib) and (lib)bare.(dylib|dll|lib) libraries will be available in the root of the build directory.
When linking against the static libbare.(a|lib) library, make sure to use whole archive linking as Bare relies on constructor functions for registering native addons. Without whole archive linking, the linker will remove the constructor functions as they aren't referenced by anything.
Bare provides a few compile options that can be configured to customize various aspects of the runtime. Compile options may be set by passing the --define option=value flag to the bare-make generate command when generating the build system.
Warning
The compile options are not covered by semantic versioning and are subject to change without warning.
| Option | Default | Description |
|---|---|---|
BARE_ENGINE |
github:holepunchto/libjs |
The JavaScript engine to use |
BARE_PREBUILDS |
ON |
Enable prebuilds for supported third-party dependencies |
Bare uses a tiered support system to manage expectations for the platforms that it targets. Targets may move between tiers between minor releases and as such a change in tier will not be considered a breaking change.
Tier 1: Platform targets for which prebuilds are provided as defined by the .github/workflows/prebuild.yml workflow. Compilation and test failures for these targets will cause workflow runs to go red.
Tier 2: Platform targets for which Bare is known to work, but without automated compilation and testing. Regressions may occur between releases and will be considered bugs.
Note
Development happens primarily on Apple hardware with Linux and Windows systems running as virtual machines.
| Platform | Architecture | Version | Tier | Notes |
|---|---|---|---|---|
| GNU/Linux | arm64 |
>= Linux 5.15, >= GNU C Library 2.35 | 1 | Ubuntu 22.04, OpenWrt 23.05 |
| GNU/Linux | x64 |
>= Linux 5.15, >= GNU C Library 2.35 | 1 | Ubuntu 22.04, OpenWrt 23.05 |
| GNU/Linux | arm64 |
>= Linux 5.10, >= musl 1.2 | 2 | Alpine 3.13, OpenWrt 22.03 |
| GNU/Linux | x64 |
>= Linux 5.10, >= musl 1.2 | 2 | Alpine 3.13, OpenWrt 22.03 |
| GNU/Linux | mips |
>= Linux 5.10, >= musl 1.2 | 2 | OpenWrt 22.03 |
| GNU/Linux | mipsel |
>= Linux 5.10, >= musl 1.2 | 2 | OpenWrt 22.03 |
| Android | arm |
>= 9 | 1 | |
| Android | arm64 |
>= 9 | 1 | |
| Android | ia32 |
>= 9 | 1 | |
| Android | x64 |
>= 9 | 1 | |
| macOS | arm64 |
>= 11.0 | 1 | |
| macOS | x64 |
>= 11.0 | 1 | |
| iOS | arm64 |
>= 14.0 | 1 | |
| iOS | x64 |
>= 14.0 | 1 | Simulator only |
| Windows | arm64 |
>= Windows 11 | 1 | |
| Windows | x64 |
>= Windows 10 | 1 |
Bare provides no standard library beyond the core JavaScript API available through the Bare namespace. Instead, we maintain a comprehensive collection of external modules built specifically for Bare.
| Module | Description | Version |
|---|---|---|
| bare-abort | Cause abnormal program termination and generate a crash report |  |
| bare-assert | Assertion library for JavaScript |  |
| bare-atomics | Native synchronization primitives for JavaScript |  |
| bare-buffer | Native buffers for JavaScript |  |
| bare-bundle | Application bundle format for JavaScript, inspired by https://github.com/electron/asar |  |
| bare-channel | Inter-thread messaging for JavaScript |  |
| bare-console | WHATWG debugging console for JavaScript |  |
| bare-crypto | Cryptographic primitives for JavaScript |  |
| bare-dgram | Native UDP for JavaScript |  |
| bare-dns | Domain name resolution for JavaScript |  |
| bare-env | Environment variable support for JavaScript |  |
| bare-events | Event emitters for JavaScript |  |
| bare-fetch | WHATWG Fetch implementation for Bare |  |
| bare-format | String formatting for JavaScript |  |
| bare-fs | Native file system for JavaScript |  |
| bare-hrtime | High-resolution timers for JavaScript |  |
| bare-http1 | HTTP/1 library for JavaScript |  |
| bare-https | HTTPS library for JavaScript |  |
| bare-inspect | Inspect objects as strings for debugging |  |
| bare-inspector | V8 inspector support for Bare |  |
| bare-ipc | Lightweight pipe-based IPC for Bare |  |
| bare-module | Module support for JavaScript |  |
| bare-net | TCP and IPC servers and clients for JavaScript |  |
| bare-os | Operating system utilities for JavaScript |  |
| bare-path | Path manipulation library for JavaScript |  |
| bare-pipe | Native I/O pipes for JavaScript |  |
| bare-process | Node.js-compatible process control for Bare |  |
| bare-querystring | URL query string utilities |  |
| bare-readline | Line editing for interactive CLIs with command history |  |
| bare-realm | Realm support for Bare |  |
| bare-repl | Read-Evaluate-Print-Loop environment for JavaScript |  |
| bare-rpc | https://github.com/holepunchto/librpc ABI compatible RPC for Bare |  |
| bare-semver | Minimal semantic versioning library for Bare |  |
| bare-signals | Native signal handling for JavaScript |  |
| bare-stream | Streaming data for JavaScript |  |
| bare-structured-clone | Structured cloning algorithm for JavaScript |  |
| bare-subprocess | Native process spawning for JavaScript |  |
| bare-tcp | Native TCP sockets for JavaScript |  |
| bare-timers | Native timers for JavaScript |  |
| bare-tls | Transport Layer Security (TLS) streams for JavaScript |  |
| bare-tty | Native TTY streams for JavaScript |  |
| bare-type | Cross-realm type predicates for Bare |  |
| bare-url | WHATWG URL implementation for JavaScript |  |
| bare-vm | Isolated JavaScript contexts for Bare |  |
| bare-worker | Higher-level worker threads for JavaScript |  |
| bare-ws | WebSocket library for JavaScript |  |
| bare-zlib | Stream-based zlib bindings for JavaScript |  |
Apache-2.0
