unenv

What is unenv?

The 'unenv' npm package is designed to provide a universal environment for JavaScript and TypeScript projects. It allows developers to create isomorphic code that can run seamlessly in both Node.js and browser environments by providing polyfills and shims for various APIs.

What are unenv's main functionalities?

Polyfills for Node.js APIs

This feature provides polyfills for Node.js APIs, allowing you to use Node.js-specific features in a browser environment. The code sample demonstrates how to use the Buffer API from Node.js in a universal environment.

const { Buffer } = require('unenv/runtime/polyfills/buffer');
const buffer = Buffer.from('Hello, world!');
console.log(buffer.toString('utf-8'));

Environment Detection

This feature allows you to detect the current environment (Node.js or browser) and execute code conditionally based on that. The code sample shows how to check if the code is running in Node.js or a browser.

const { isNode, isBrowser } = require('unenv');
if (isNode) {
  console.log('Running in Node.js');
} else if (isBrowser) {
  console.log('Running in the browser');
}

Universal Fetch API

This feature provides a universal Fetch API that works in both Node.js and browser environments. The code sample demonstrates how to make a fetch request and handle the response.

const fetch = require('unenv/runtime/polyfills/fetch');
fetch('https://api.example.com/data')
  .then(response => response.json())
  .then(data => console.log(data));

Other packages similar to unenv

isomorphic-fetch

The 'isomorphic-fetch' package provides a Fetch API implementation that works in both Node.js and browser environments. It is similar to the Fetch API polyfill provided by 'unenv', but it focuses solely on fetch functionality.

universal-env

The 'universal-env' package helps in detecting the current environment (Node.js or browser) and provides utility functions for environment-specific code. It is similar to the environment detection feature of 'unenv'.

node-polyfill-webpack-plugin

The 'node-polyfill-webpack-plugin' package provides polyfills for Node.js core modules in a Webpack environment. It is similar to the polyfills provided by 'unenv', but it is specifically designed for use with Webpack.

README

🕊️ unenv

[!NOTE] You are on the development (v2) branch. Check out v1 for the current release.

unenv provides polyfills to add Node.js compatibility for any JavaScript runtime, including browsers and edge workers.

🌟 Used by

• Nitro
• Nuxt
• Cloudflare
• ESM.sh

Usage

The defineEnv utility can generate a target environment configuration.

import { defineEnv } from "unenv";

const { env } = defineEnv({
  nodeCompat: true,
  npmShims: true,
  resolve: true,
  overrides: {},
  presets: [],
});

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

You can then integrate the env object with your build tool:

Bundler	alias	inject	external
rollup	@rollup/plugin-alias	@rollup/plugin-inject	external
rolldown	resolve.alias	inject	external
vite	resolve.alias	@rollup/plugin-inject	ssr.external
esbuild	alias	inject	external
rspack	resolve.alias	-	externals
webpack	resolve.alias	webpack-plugin-inject	externals

Options

• nodeCompat: (default: true)
  • Add alias entries for Node.js builtins as <id> and node:<id>.
  • Add inject entries for Node.js globals global, Buffer, and process.
• npmShims: (default: false)
  • Add alias entries to replace npm packages like node-fetch with lighter shims.
• resolve: (default: false) Resolve config values to absolute paths.
• overrides: Additional overrides for env config.
• presets: Additional presets (for example @cloudflare/unenv-preset).

unenv/ polyfills

You can also directly import unenv/ polyfills:

Polyfills	Description	Source
unenv/mock/*	Mocking utils	src/runtime/mock
unenv/node/*	APIs compatible with Node.js API	src/runtime/node
unenv/npm/*	NPM package shims	src/runtime/npm
unenv/polyfill/*	Global polyfills	src/runtime/polyfill
unenv/web/*	Subset of Web APIs	src/runtime/web

Node.js compatibility

unenv replaces Node.js built-in modules compatible with any runtime (view source).

• ✅ node:assert
• ✅ node:assert/strict
• ✅ node:async_hooks
• ✅ node:buffer
• ✅ node:child_process
• ✅ node:cluster
• ✅ node:console
• ✅ node:constants
• ✅ node:crypto
• ✅ node:dgram
• ✅ node:diagnostics_channel
• ✅ node:dns
• ✅ node:dns/promises
• ✅ node:domain
• ✅ node:events
• ✅ node:fs
• ✅ node:fs/promises
• ✅ node:http
• ✅ node:http2
• ✅ node:https
• ✅ node:inspector
• ✅ node:inspector/promises
• ✅ node:module
• ✅ node:net
• ✅ node:os
• ✅ node:path
• ✅ node:path/posix
• ✅ node:path/win32
• ✅ node:perf_hooks
• ✅ node:process
• ✅ node:punycode
• ✅ node:querystring
• ✅ node:readline
• ✅ node:readline/promises
• ✅ node:repl
• ✅ node:stream
• ✅ node:stream/consumers
• ✅ node:stream/promises
• ✅ node:stream/web
• ✅ node:string_decoder
• ✅ node:sys
• ✅ node:timers
• ✅ node:timers/promises
• ✅ node:tls
• ✅ node:trace_events
• ✅ node:tty
• ✅ node:url
• ✅ node:util
• ✅ node:util/types
• ✅ node:v8
• ✅ node:vm
• ✅ node:wasi
• ✅ node:worker_threads
• ✅ node:zlib

Manual mocking

// Magic proxy to replace any unknown API
import MockProxy from "unenv/mock/proxy";

// You can also create named mocks
const lib = MockProxy.__createMock__("lib", {
  /* overrides */
});

(view source)

Nightly release channel

You can use the nightly release channel to try the latest changes in the main branch via unenv-nightly.

If directly using unenv in your project:

{
  "devDependencies": {
    "unenv": "npm:unenv-nightly"
  }
}

If using unenv via another tool (Nuxt or Nitro) in your project:

{
  "resolutions": {
    "unenv": "npm:unenv-nightly"
  }
}

License

Published under the MIT license. Made by @pi0 and community 💛

🤖 auto updated with automd

Changelog

v2.0.0-rc.8

compare changes

🩹 Fixes

• Resolve built-in modules as node: (6fb091b)

❤️ Contributors

• Pooya Parsa (@pi0)