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.
path
✓ import { join } from 'path';
✗ import { join } from 'meteor-node-stubs/path';
Developers import Node.js built-in modules directly; Meteor's build system automatically aliases to `meteor-node-stubs` implementations on the client. Direct import from `meteor-node-stubs/path` is incorrect and unnecessary.
process
✓ console.log(process.env.NODE_ENV);
✗ import process from 'process';
The `process` object is globally available in Meteor client environments due to `meteor-node-stubs`, making direct named or default imports typically redundant. The `process` global is a common pattern for Node.js built-ins.
Buffer
✓ import { Buffer } from 'buffer';
✗ import { Buffer } from 'meteor-node-stubs/buffer';
Like other Node.js built-ins, `Buffer` is imported using its standard Node.js module name. The stubbed version from `meteor-node-stubs` is transparently provided.
Demonstrates using Node.js built-in modules like `path` and `process` in client-side Meteor code, relying on `meteor-node-stubs` to provide browser-compatible implementations.
import { Meteor } from 'meteor/meteor';
import { basename, extname } from 'path'; // Importing Node.js 'path' module
if (Meteor.isClient) {
Meteor.startup(() => {
// This code runs only on the client (browser)
const filePath = '/home/user/document.txt';
const baseName = basename(filePath);
const extension = extname(filePath);
console.log(`Original Path: ${filePath}`);
console.log(`Base Name: ${baseName}`);
console.log(`File Extension: ${extension}`);
// Demonstrate another common stub, 'process'
// process.env is stubbed for browser compatibility
console.log(`Environment (from stubbed process): ${process.env.NODE_ENV ?? 'development'}`);
console.log(`Is browser? (from stubbed process): ${process.browser ?? true}`);
// Example of a function that might not be fully stubbed or is a no-op
try {
// The 'fs' module is typically not fully implemented in browser stubs.
// Attempting to use server-side filesystem operations will fail.
// import * as fs from 'fs'; // If actually imported, would be at top
// fs.readFile('/some/file.txt', () => {});
console.log("Attempted to use fs (may not work as expected in browser stubs).");
} catch (e) {
console.warn("fs module is likely not fully implemented in browser stubs:", e.message);
}
});
}
Debug
Known issues
breakingA critical security vulnerability in `crypto-browserify` (a sub-dependency) led to an urgent update of `meteor-node-stubs` (e.g., to version `1.2.8` in April 2024). This update involved forking the vulnerable dependency and caused breaking changes for some users attempting to `import 'path'` or `import 'os'` in client-side code.fixEnsure `meteor-node-stubs` is updated to the latest compatible version (`meteor npm update meteor-node-stubs`) and review client-side imports of Node.js built-ins for compatibility. If issues persist, refer to Meteor community forums for specific migration guidance.
affects: >=1.2.8
gotchaThis package provides *stubs* or browser-compatible implementations for Node.js built-in modules, not full Node.js functionality. Developers must not assume complete Node.js API parity on the client. Many functions may be limited, no-ops, or throw errors (e.g., `fs.readFile` will not work in the browser).fixRefactor client-side code to avoid Node.js-specific APIs that lack full browser equivalents. For critical functionality, explore browser-native alternatives or dedicated browser polyfill packages.
affects: >=1.0.0
gotchaClient-side imports of Node.js modules, even if stubbed, can significantly increase the client-side bundle size, particularly for modules with large browser polyfills (e.g., `crypto` can add 630KB to the bundle).fixImplement careful code-splitting and dynamic imports (`import()`) for modules not immediately required at application startup. Analyze your bundle size using Meteor's bundle visualizer to identify and optimize large imports.
affects: >=1.0.0
deprecatedThe official GitHub repository for `meteor-node-stubs` (meteor/node-stubs) is archived and set to read-only, directing users to the main Meteor repository for current code. While the package itself is actively maintained, relying on the archived repository for issues or pull requests is no longer possible.fixRefer to the main Meteor repository and community channels for reporting issues or contributing. Be aware that GitHub's 'archived' status for the specific package repository might lead to confusion about its maintenance status.
affects: >=1.2.0
breakingWith Meteor 3.x's adoption of Rspack as the default bundler, there are ongoing discussions regarding the future role of `meteor-node-stubs`. Rspack has its own polyfill handling for some Node built-ins, which might lead to `meteor-node-stubs` being optional or removed as a default dependency in future Meteor versions (e.g., 3.4+). This could require manual addition for specific needs.fixMonitor Meteor release notes for versions 3.4 and beyond. If upgrading, be prepared to explicitly install `meteor-node-stubs` if your application or its dependencies rely on browser polyfills not covered by Rspack's default configuration.
affects: >=3.4.0 (potential future change)
Errors
Common errors & fixes
Uncaught Error: Cannot find module 'path' (or 'os', 'util', etc.)
A Node.js built-in module is imported on the client, but `meteor-node-stubs` is missing, an outdated version, or the Meteor build system isn't correctly processing the stub.
fixEnsure `meteor-node-stubs` is installed (`meteor npm install --save meteor-node-stubs`) and updated to the latest compatible version (`meteor npm update meteor-node-stubs`). For older Meteor versions, check the Meteor Guide for specific installation instructions.
Uncaught ReferenceError: process is not defined
The global `process` object, normally provided by Node.js or `meteor-node-stubs` in the browser, is not available, indicating a failure in the stubbing mechanism for the `process` module.
fixVerify `meteor-node-stubs` is correctly installed and that your Meteor app is bundling it for the client. If using Meteor 3.x with Rspack, ensure Rspack's polyfilling for `process` is active.
TypeError: fs.readFile is not a function
Attempting to use a function or feature of a Node.js built-in module (`fs` in this case) that is either not implemented or only partially implemented by its browser stub. `meteor-node-stubs` provides minimal browser compatibility, not a full Node.js environment.
fixRefactor client-side code to avoid Node.js-specific APIs that lack full browser equivalents. For critical functionality, consider finding a browser-native alternative or a dedicated browser polyfill package.
npm ERR! path /path/to/project/node_modules/meteor-node-stubs ... EPERM: operation not permitted
File permission issues during `npm install` or `npm update`, preventing installation or modification of files within the `meteor-node-stubs` package.
fixTry running `meteor npm cache clean --force`, then remove the `node_modules` directory (`rm -rf node_modules`) and `package-lock.json` file. Reinstall dependencies with `meteor npm install`. If permissions persist, check your user's file system permissions for the project directory.
Audit
Dependencies
assertrequiredProvides a browser-compatible assertion module.
bufferrequiredProvides a browser-compatible Buffer class.
stream-browserifyrequiredProvides a browser-compatible stream API.
processrequiredProvides a browser-compatible `process` global.
@meteorjs/crypto-browserifyrequiredProvides a browser-compatible crypto module, forked by Meteor for security updates.
utilrequiredProvides browser-compatible Node.js utilities.