{"id":11302,"library":"meteor-node-stubs","title":"Meteor Node Stubs","description":"meteor-node-stubs provides browser-compatible stub implementations for Node.js built-in modules (e.g., `path`, `buffer`, `process`, `crypto`). It enables NPM packages, even those initially for Node.js, to run within Meteor client-side applications by transparently redirecting imports to these browser-friendly stubs, requiring no manual configuration. The current stable version is 1.2.27, with releases tied to the broader Meteor ecosystem's update cycle for security and compatibility, including Meteor 3.x. Its key differentiator is automatic integration with Meteor's build process, minimizing client bundle bloat by only including necessary stubs.","status":"active","version":"1.2.27","language":"javascript","source_language":"en","source_url":"https://github.com/meteor/meteor#devel","tags":["javascript","stubs","shims","node","builtins","core","modules","browserify","webpack"],"install":[{"cmd":"npm install meteor-node-stubs","lang":"bash","label":"npm"},{"cmd":"yarn add meteor-node-stubs","lang":"bash","label":"yarn"},{"cmd":"pnpm add meteor-node-stubs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides a browser-compatible assertion module.","package":"assert","optional":false},{"reason":"Provides a browser-compatible Buffer class.","package":"buffer","optional":false},{"reason":"Provides a browser-compatible stream API.","package":"stream-browserify","optional":false},{"reason":"Provides a browser-compatible `process` global.","package":"process","optional":false},{"reason":"Provides a browser-compatible crypto module, forked by Meteor for security updates.","package":"@meteorjs/crypto-browserify","optional":false},{"reason":"Provides browser-compatible Node.js utilities.","package":"util","optional":false}],"imports":[{"note":"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.","wrong":"import { join } from 'meteor-node-stubs/path';","symbol":"path","correct":"import { join } from 'path';"},{"note":"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.","wrong":"import process from 'process';","symbol":"process","correct":"console.log(process.env.NODE_ENV);"},{"note":"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.","wrong":"import { Buffer } from 'meteor-node-stubs/buffer';","symbol":"Buffer","correct":"import { Buffer } from 'buffer';"}],"quickstart":{"code":"import { Meteor } from 'meteor/meteor';\nimport { basename, extname } from 'path'; // Importing Node.js 'path' module\n\nif (Meteor.isClient) {\n  Meteor.startup(() => {\n    // This code runs only on the client (browser)\n    const filePath = '/home/user/document.txt';\n    const baseName = basename(filePath);\n    const extension = extname(filePath);\n\n    console.log(`Original Path: ${filePath}`);\n    console.log(`Base Name: ${baseName}`);\n    console.log(`File Extension: ${extension}`);\n\n    // Demonstrate another common stub, 'process'\n    // process.env is stubbed for browser compatibility\n    console.log(`Environment (from stubbed process): ${process.env.NODE_ENV ?? 'development'}`);\n    console.log(`Is browser? (from stubbed process): ${process.browser ?? true}`);\n\n    // Example of a function that might not be fully stubbed or is a no-op\n    try {\n      // The 'fs' module is typically not fully implemented in browser stubs.\n      // Attempting to use server-side filesystem operations will fail.\n      // import * as fs from 'fs'; // If actually imported, would be at top\n      // fs.readFile('/some/file.txt', () => {}); \n      console.log(\"Attempted to use fs (may not work as expected in browser stubs).\");\n    } catch (e) {\n      console.warn(\"fs module is likely not fully implemented in browser stubs:\", e.message);\n    }\n  });\n}","lang":"javascript","description":"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."},"warnings":[{"fix":"Ensure `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.","message":"A 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.","severity":"breaking","affected_versions":">=1.2.8"},{"fix":"Refactor 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.","message":"This 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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement 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.","message":"Client-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).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer 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.","message":"The 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.","severity":"deprecated","affected_versions":">=1.2.0"},{"fix":"Monitor 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.","message":"With 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.","severity":"breaking","affected_versions":">=3.4.0 (potential future change)"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `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.","cause":"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.","error":"Uncaught Error: Cannot find module 'path' (or 'os', 'util', etc.)"},{"fix":"Verify `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.","cause":"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.","error":"Uncaught ReferenceError: process is not defined"},{"fix":"Refactor 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.","cause":"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.","error":"TypeError: fs.readFile is not a function"},{"fix":"Try 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.","cause":"File permission issues during `npm install` or `npm update`, preventing installation or modification of files within the `meteor-node-stubs` package.","error":"npm ERR! path /path/to/project/node_modules/meteor-node-stubs ... EPERM: operation not permitted"}],"ecosystem":"npm"}