Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
defineEnv
✓ import { defineEnv } from 'unenv'
✗ const { defineEnv } = require('unenv')
This is the primary entry point for configuring environments in `unenv` v2.x. `unenv` is ESM-first, and CommonJS `require` is generally not supported for v2 API.
env
✓ import { env } from 'unenv'
This was the primary entry point for `unenv` v1.x. For new projects or migrating to v2, `defineEnv` is recommended.
nodeless, cloudflare
✓ import { nodeless, cloudflare } from 'unenv'
✗ import { presets } from 'unenv' // Presets are named exports
Environment presets (e.g., `nodeless`, `cloudflare`, `deno`, `node`) are directly named exports from the `unenv` package. For specific Cloudflare Workers presets, `@cloudflare/unenv-preset` may be used.
Buffer
✓ import { Buffer } from 'unenv/node/buffer'
✗ import { Buffer } from 'buffer'
For Node.js built-ins, `unenv` provides shims via subpath exports under `unenv/node/`. Direct imports like `import { Buffer } from 'buffer'` might resolve to Node.js native modules and break in non-Node environments without `unenv`'s intervention.
This quickstart demonstrates how to configure `unenv` using the `defineEnv` utility for a Cloudflare Workers environment. It shows how to enable Node.js compatibility, apply environment-specific presets, and inspect the generated aliases, injections, polyfills, and externalizations for use in bundlers. It also illustrates how `unenv` handles unimplemented Node.js APIs by providing a runtime error, preventing unexpected behavior.
import { defineEnv, nodeless, cloudflare } from 'unenv';
import fs from 'node:fs'; // Example of a Node.js built-in that will be shimmed
// Configure unenv for a Cloudflare Workers environment, enabling Node.js compatibility
// and auto-mocking for unimplemented APIs.
const { alias, inject, polyfill, external } = defineEnv({
nodeCompat: true, // Enable shims for Node.js built-ins and globals
npmShims: true, // Enable shims for common npm packages
presets: [
nodeless, // Base preset for non-Node.js environments
cloudflare // Cloudflare Workers specific compatibility
],
overrides: {
// Custom overrides if needed, e.g., to replace specific modules
'node:fs': 'unenv/mock/proxy-cjs' // Ensure fs is fully mocked or aliased
}
});
console.log('Generated Aliases:', alias);
console.log('Injected Globals:', inject);
console.log('Required Polyfills:', polyfill);
console.log('Externalized Modules:', external);
// This output can then be used in a bundler configuration (e.g., Vite, Webpack, Rollup)
// to apply the environment transformations.
// Example: How a bundler might use 'alias' output
// const viteConfig = {
// resolve: {
// alias: Object.entries(alias).map(([find, replacement]) => ({ find, replacement }))
// }
// };
// console.log(viteConfig);
// Example: Demonstrate an unimplemented API call with a mock
try {
fs.readFileSync('./test.txt', 'utf8');
} catch (e) {
console.log(`
Attempted to use fs.readFileSync: ${e.message}`);
console.log('This demonstrates how unenv mocks unimplemented APIs by throwing an error, indicating it is not available in the target runtime.');
}
Debug
Known issues
breakingThe `env` utility from v1.x has been replaced by `defineEnv` in `unenv` v2.x. While v1.x is stable, new projects or migrations should use `defineEnv` for enhanced configuration options and future compatibility.fixMigrate `import { env } from 'unenv'` to `import { defineEnv } from 'unenv'` and adjust configuration object structure accordingly. Refer to the `unenv` v2 documentation. affects: >=2.0.0-rc
gotchaSome Node.js APIs are not fully implemented by `unenv` for all target runtimes. Instead, `unenv` might provide 'mock' implementations that throw errors or do nothing when called. This prevents silent failures but requires developers to be aware of unsupported APIs.
gotchaWhen targeting Cloudflare Workers, ensure that the `nodejs_compat` or `nodejs_compat_v2` compatibility flag is enabled in your `wrangler.toml` configuration. Without this, Node.js API polyfills might not function correctly or be included.
deprecatedPresets like `deno` and `cloudflare` in `unenv` v2.x are explicitly marked as 'experimental' and their behavior or API might change in future release candidates or stable versions. Use with caution in production environments.
Errors
Common errors & fixes
Could not resolve "events"
An npm package attempting to import a Node.js built-in module (like `events`, `path`, `fs`) in a non-Node.js environment (e.g., browser, worker) without `unenv` properly shimming or aliasing it.
fixEnsure `unenv` is correctly configured in your build pipeline to provide shims and aliases for Node.js built-ins. For `defineEnv`, set `nodeCompat: true`. If using a specific preset like `nodeless` or `cloudflare`, ensure it's applied.
[unenv] <method name> is not implemented yet!
Calling a method of a Node.js API (e.g., `fs.readFileSync`) that `unenv` has provided a mock implementation for, but the actual functionality is not available or polyfilled in the target runtime.
fixIdentify the unsupported Node.js API. If the functionality is critical, you may need to implement a custom shim using `unenv`'s `overrides` option or find an alternative, platform-agnostic library. Review `unenv`'s documentation for supported API coverage per runtime.
Audit
Dependencies
No dependency data recorded yet.