LogoLogo
  • Pear by Holepunch
  • Pear runtime
    • Command-Line-Interface (CLI)
    • Application-Programming-Interface (API)
    • Application Configuration
    • Troubleshooting Applications
  • Bare reference
    • Overview
    • Application-Programming-Interface (API)
    • Node.js Compatibility with Bare
    • Bare Modules
    • Troubleshooting with Bare
  • Guides
    • Getting Started
    • Starting a Pear Desktop Project
    • Making a Pear Desktop Application
    • Starting a Pear Terminal Project
    • Making a Pear Terminal Application
    • Sharing a Pear Application
    • Marking a Release
    • Making a Bare Mobile Application
    • Debugging a Pear Terminal Application
    • Creating a Pear Init Template
  • Building blocks
    • Hypercore
    • Hyperbee
    • Hyperdrive
    • Autobase
    • HyperDHT
    • Hyperswarm
  • How-tos
    • Connect two peers
    • Connect many peers
    • Replicate & persist
    • Manage multiple Hypercores
    • Share append-only databases
    • Create a p2p filesystem
  • Helpers
    • Corestore
    • Localdrive
    • Mirrordrive
    • Secretstream
    • Compact encoding
    • Protomux
  • Tools
    • Hypershell
    • Hypertele
    • Hyperbeam
    • Hyperssh
    • Drives
  • Apps
    • Keet
  • Examples
    • Bare on Mobile
    • React App using Pear
Powered by GitBook

Copyright © 2024 - 2025 Holepunch, S.A. de C.V. All rights reserved.

On this page
  • Currently supported modules
  • Config for the Node.js stdlib
  • Consuming dependencies that use core Node.js modules
  • Consuming dependencies using NPM Aliases
  • Example of using fs in a project using aliases
  • Consuming dependencies using Import Maps
  • Example of using fs in a project using import maps
  1. Bare reference

Node.js Compatibility with Bare

Last updated 6 months ago

Bare offers great compatibility with Node.js counterparts. Most of the modules and APIs used by developers are covered and supported.

Currently supported modules

  • assert: (through npm:bare-node-assert)

  • buffer: (through npm:bare-node-buffer)

  • child_process: (through npm:bare-node-child-process)

  • console: (through npm:bare-node-console)

  • crypto: (through npm:bare-node-crypto)

  • events: (through npm:bare-node-events)

  • fs: (through npm:bare-node-fs)

  • http: (through npm:bare-node-http)

  • https: (through npm:bare-node-https)

  • inspector: (through npm:bare-node-inspector)

  • module: (through npm:bare-node-module)

  • os: (through npm:bare-node-os)

  • path: (through npm:bare-node-path)

  • process: (through npm:bare-node-process)

  • readline: (through npm:bare-node-readline)

  • repl: (through npm:bare-node-repl)

  • stream: (through npm:bare-node-stream)

  • timers: (through npm:bare-node-timers)

  • tls: (through npm:bare-node-tls)

  • tty: (through npm:bare-node-tty)

  • url: (through npm:bare-node-url)

  • util: (through npm:bare-node-util)

  • worker_threads: (through npm:bare-node-worker-threads)

  • zlib: (through npm:bare-node-zlib)

Config for the Node.js stdlib

To get the full Node.js compatible layer that Bare currently supports add the following lines to the package.json file.

{
  "dependencies": {
    "bare-assert": "^1.0.1",
    "assert": "npm:bare-node-assert",
    "bare-buffer": "^2.3.0",
    "buffer": "npm:bare-node-buffer",
    "bare-subprocess": "^2.0.4",
    "child_process": "npm:bare-node-child-process",
    "bare-console": "^4.1.0",
    "console": "npm:bare-node-console",
    "bare-crypto": "^1.0.0",
    "crypto": "npm:bare-node-crypto",
    "bare-events": "^2.2.0",
    "events": "npm:bare-node-events",
    "bare-fs": "^2.1.5",
    "fs": "npm:bare-node-fs",
    "bare-http1": "^2.0.3",
    "http": "npm:bare-node-http",
    "bare-https": "^1.0.0",
    "https": "npm:bare-node-https",
    "bare-inspector": "^1.1.2",
    "inspector": "npm:bare-node-inspector",
    "bare-module": "^1.2.5",
    "module": "npm:bare-node-module",
    "bare-os": "^2.2.0",
    "os": "npm:bare-node-os",
    "bare-path": "^2.1.0",
    "path": "npm:bare-node-path",
    "bare-process": "^1.3.0",
    "process": "npm:bare-node-process",
    "bare-readline": "^1.0.0",
    "readline": "npm:bare-node-readline",
    "bare-repl": "^1.0.3",
    "repl": "npm:bare-node-repl",
    "bare-stream": "^1.0.0",
    "stream": "npm:bare-node-stream",
    "bare-timers" : "^1.0.0",
    "timers": "npm:bare-node-timers",
    "bare-tls": "^1.0.0",
    "tls": "npm:bare-node-tls",
    "bare-tty": "^3.2.0",
    "tty": "npm:bare-node-tty",
    "bare-url": "^1.0.7",
    "url": "npm:bare-node-url",
    "bare-utils": "^1.0.0",
    "util": "npm:bare-node-util",
    "bare-worker": "^1.0.0",
    "worker_threads": "npm:bare-node-worker-threads",
    "bare-zlib": "^1.0.0",
    "zlib": "npm:bare-node-zlib"
  }
}

Consuming dependencies that use core Node.js modules

Consuming dependencies using NPM Aliases

NPM aliasing is a feature that allows developers to define custom names, or aliases, for their dependencies. This enables them to use a more intuitive or project-specific naming convention instead of relying on the package’s official name.

In your project’s package.json file, use the alias field to specify package aliases. For example:

{
  "dependencies": {
    "my-package": "npm:actual-package@1.0.0"
  }
}

After defining aliases, install the dependencies as usual:

npm install

Then, in the code import the aliased package:

// Instead of using the name of the package, use the alias
const myPackage = require('my-package');

Example of using fs in a project using aliases

Start a new project

Init a new terminal project.

mkdir test-fs
cd test-fs
pear init --yes --type=terminal

Replace the contents of index.js with the following:

import * as fs from 'node:fs';

async function test() {
  try {
    await fs.promises.writeFile('test.txt', `Hello ${global.Bare ? 'Bare' : 'Node'}`);
    const content = await fs.promises.readFile('test.txt', 'utf8');
    console.log('File content:', content);
    await fs.promises.unlink('test.txt');
    console.log('Test successful!');
  } catch (error) {
    console.error('Test failed:', error);
  }
}

test();

This will create a file called test.txt and write a string to it. It will then read the file and log the content to the console.

Now run the file using Node.js.

node index.js

This should output the following.

File content: Hello Node 
Test successful!

If we run the same project using Bare, it will fail with the MODULE_NOT_FOUND error.

Add the following lines to the package.json file.

{
  "dependencies": {
    "bare-fs": "^2.1.5",
    "fs": "npm:bare-node-fs"
  }
}

This installs bare-fs newer than ^2.1.5. Then, adds alias fs to the wrapper npm:bare-node-fs.

The only thing the wrapper does is module.exports = require('bare-fs') and at version *, meaning the version that is specified is used.

Using the wrapper saves space as npm will only include bare-fs once if something else installs it.

Now install the dependencies.

npm install

Now run the project using Bare.

bare index.js

This should output the following.

File content: Hello Bare
Test successful!

Consuming dependencies using Import Maps

When writing a module that uses fs the mapping can be specified directly in the module instead of relying on the compatible. This can be achieved using an 'import map'.

{
  "imports": {
    "fs": {
      "bare": "bare-fs",
      "default": "fs"
    },
    "fs/*": {
      "bare": "bare-fs/*",
      "default": "fs/*"
    }
  },
  "optionalDependencies": {
    "bare-fs": "^2.1.5"
  }
}

Let's take the fs example and use import maps instead of aliases.

Example of using fs in a project using import maps

Start a new terminal project

mkdir test-fs
cd test-fs
pear init --yes --type=terminal

Change the import statement at the top:

import * as fs from 'fs';

Add the following fields to the package.json:

{
  "imports": {
    "fs": {
      "bare": "bare-fs",
      "default": "fs"
    }
  },
  "optionalDependencies": {
    "bare-fs": "^2.1.5"
  }
}

Install the dependencies:

npm install

Now run the file using Node.js.

node index.js

This should output the following.

File content: Hello Node 
Test successful!

Run the same file using Bare

bare index.js

It should log the following output:

File content: Hello Bare 
Test successful!

This way the module is in full control of exactly which version of fs is bound to Bare.

This is the best option, as it provides the best of both worlds. Node.js compatibility, but with full control of the dependencies.

If the project dependencies use core modules, use or to consume the Bare version of those modules.

Make sure is installed on your system. This can be checked by running node -v in the terminal.

Now to make it compatible with Bare, we will create an alias for fs in our project and install the respective Bare package to make it work again. In this case it's .

For example uses fs and to work in both Bare and Node.js it adds the following import map to the package.json file.

Replace contents of index.js with the code from the NPM aliases .

bare-assert
bare-buffer
bare-subprocess
bare-console
bare-crypto
bare-events
bare-fs
bare-http1
bare-https
bare-inspector
bare-module
bare-os
bare-path
bare-process
bare-readline
bare-repl
bare-stream
bare-timers
bare-tls
bare-tty
bare-url
bare-utils
bare-worker
bare-zlib
Node.js
bare-fs
Localdrive
Node.js
NPM aliases
import maps
example