unenv

unenv is a framework-agnostic system that allows converting JavaScript code to be platform agnostic and work in any environment including Browsers, Workers, Node.js, or JavaScript runtime.

[!NOTE] You are on the legacy (v1) branch. Checkout main branch for latest development.

Install

# Using npm
npm i -D unenv

# Using yarn
yarn add --dev unenv

# Using pnpm
pnpm add -D unenv

Usage

Using env utility and built-in presets, unenv will provide an abstract configuration that can be used in building pipelines (rollup.js, webpack, etc.).

import { env } from "unenv";

const { alias, inject, polyfill, external } = env({}, {}, {});

Note: You can provide as many presets as you want. unenv will merge them internally and the right-most preset has a higher priority.

Presets

node

(view source)

Suitable to convert universal libraries working in Node.js.

• Add supports for global fetch API
• Set Node.js built-ins as externals

import { env, nodeless } from "unenv";

const envConfig = env(node, {});

nodeless

(view source)

Suitable to transform libraries made for Node.js to run in other JavaScript runtimes.

import { env, nodeless } from "unenv";

const envConfig = env(nodeless, {});

deno

(view source)

This preset can be used to extend nodeless to use Deno's Node.js API Compatibility (docs, docs).

[!WARNING] This preset is experimental and behavior might change!

import { env, nodeless, deno } from "unenv";

const envConfig = env(nodeless, deno, {});

cloudflare

(view source)

This preset can be used to extend nodeless to use Cloudflare Worker Node.js API Compatibility (docs).

[!WARNING] This preset is experimental and behavior might change!

[!NOTE] Make sure to enable nodejs_compat compatibility flag.

import { env, nodeless, cloudflare } from "unenv";

const envConfig = env(nodeless, cloudflare, {});

vercel

This preset can be used to extend nodeless to use Vercel Edge Node.js API Compatibility (docs).

[!WARNING] This preset is experimental and behavior might change!

import { env, nodeless, vercel } from "unenv";

const envConfig = env(nodeless, vercel, {});

Built-in Node.js modules

unenv provides a replacement for all Node.js built-ins for cross-platform compatibility.

| Module | Status | Source | | --------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------ | | node:assert | Mocked | - | | node:async_hooks | Polyfilled | unenv/node/async_hooks | | node:buffer | Polyfilled | unenv/node/buffer | | node:child_process | Mocked | - | | node:cluster | Mocked | - | | node:console | Mocked | - | | node:constants | Mocked | - | | node:crypto | Polyfilled | unenv/node/crypto | | node:dgram | Mocked | - | | node:diagnostics_channel | Mocked | - | | node:dns | Mocked | - | | node:domain | Mocked | - | | node:events | Polyfilled | unenv/node/events | | node:fs | Polyfilled | unenv/node/fs | | node:fs/promises | Polyfilled | unenv/node/fs/promises | | node:http2 | Mocked | - | | node:http | Polyfilled | unenv/node/http | | node:https | Polyfilled | unenv/node/https | | node:inspector | Mocked | - | | node:module | Polyfilled | unenv/node/module - | | node:net | Polyfilled | unenv/node/net | | node:os | Mocked | - | | node:path | Polyfilled | unenv/node/path | | node:perf_hooks | Mocked | - | | node:process | Polyfilled | unenv/node/process | | node:punycode | Mocked | - | | node:querystring | Mocked | - | | node:readline | Mocked | - | | node:repl | Mocked | - | | node:stream | Polyfilled | unenv/node/stream | | node:stream/consumers | Mocked | unenv/node/stream/consumers | | node:stream/promises | Mocked | unenv/node/stream/promises | | node:stream/web | Native | unenv/node/stream/web | | node:string_decoder | Polyfilled | unenv/node/string_decoder | | node:sys | Mocked | - | | node:timers | Mocked | - | | node:timers/promises | Mocked | - | | node:tls | Mocked | - | | node:trace_events | Mocked | - | | node:tty | Mocked | - | | node:url | Polyfilled | unenv/node/url | | node:util | Polyfilled | unenv/node/util | | node:util/types | Polyfilled | unenv/node/util/types | | node:v8 | Mocked | - | | node:vm | Mocked | - | | node:wasi | Mocked | - | | node:worker_threads | Mocked | - | | node:zlib | Mocked | - |

npm packages

unenv provides a replacement for common npm packages for cross platform compatibility.

| Package | Status | Source | | ----------------------------------------------------------- | --------------------------- | ----------------------------------------------------------------- | | npm/consola | Use native console | unenv/runtime/npm/consola | | npm/cross-fetch | Use native fetch | unenv/runtime/npm/cross-fetch | | npm/debug | Mocked with console.debug | unenv/runtime/npm/debug | | npm/fsevents | Mocked | unenv/runtime/npm/fsevents | | npm/inherits | Inlined | unenv/runtime/npm/inherits | | npm/mime-db | Minimized | unenv/runtime/npm/mime-db | | npm/mime | Minimized | unenv/runtime/npm/mime | | npm/node-fetch | Use native fetch | unenv/runtime/npm/node-fetch | | npm/whatwg-url | Use native URL | unenv/runtime/npm/whatwg-url |

Auto-mocking proxy

import MockProxy from "unenv/runtime/mock/proxy";

console.log(MockProxy().foo.bar()[0]);

The above package doesn't work outside of Node.js and neither we need any platform-specific logic! When aliasing os to mock/proxy-cjs, it will be auto-mocked using a Proxy Object which can be recursively traversed like an Object, called like a Function, Iterated like an Array, or instantiated like a Class.

We use this proxy for auto-mocking unimplemented internals. Imagine a package does this:

const os = require("node:os");
if (os.platform() === "windows") {
  /* do some fix */
}
module.exports = function main() {
  return "Hello world"
}

By aliasing os to unenv/runtime/mock/proxy-cjs, the code will be compatible with other platforms.

Other polyfills

To discover other polyfills, please check ./src/runtime.

License

MIT