{"record":{"id":"292614dfabbc1b56","repo":"oxc-project/oxc","slug":"do-not-import-node-js-builtin-module-module-name","errorCode":null,"errorMessage":"Do not import Node.js builtin module `{module_name}`","messagePattern":"Do not import Node\\.js builtin module `(.+?)`","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/import/no_nodejs_modules.rs","lineNumber":21,"sourceCode":"    AstKind,\n    ast::{Expression, TSModuleReference},\n};\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::{GetSpan, Span};\nuse oxc_str::CompactStr;\nuse rustc_hash::FxHashSet;\nuse schemars::JsonSchema;\nuse serde::{Deserialize, Serialize};\n\nuse crate::{\n    AstNode,\n    context::LintContext,\n    rule::{DefaultRuleConfig, Rule},\n};\n\nfn no_nodejs_modules_diagnostic(span: Span, module_name: &str) -> OxcDiagnostic {\n    OxcDiagnostic::warn(format!(\"Do not import Node.js builtin module `{module_name}`\"))\n        .with_help(\"Use a browser-compatible alternative or add this module to the `allow` list if Node.js usage is intentional.\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone, Serialize, Deserialize, JsonSchema)]\n#[schemars(rename_all = \"camelCase\", deny_unknown_fields)]\npub struct NoNodejsModulesConfig {\n    /// Array of names of allowed modules. Defaults to an empty array.\n    allow: FxHashSet<CompactStr>,\n}\n\n#[derive(Debug, Default, Clone, Deserialize, Serialize, JsonSchema)]\npub struct NoNodejsModules(Box<NoNodejsModulesConfig>);\n\nimpl std::ops::Deref for NoNodejsModules {\n    type Target = NoNodejsModulesConfig;\n\n    fn deref(&self) -> &Self::Target {","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/import/no_nodejs_modules.rs#L3-L39","documentation":"Diagnostic from the oxlint rule import/no-nodejs-modules (style category). It fires when a module imports a Node.js builtin — `fs`, `node:path`, `crypto`, etc. — signaling that Node-only code reached a context meant to be browser-compatible. The help offers two outs: use a browser-compatible alternative, or add the module to the `allow` list when Node usage is intentional (e.g. SSR-only or build-time code).","triggerScenarios":"An import whose bare specifier names a Node builtin (with or without the `node:` prefix) and is not in the configured `allow` set — reported from no_nodejs_modules_diagnostic at crates/oxc_linter/src/rules/import/no_nodejs_modules.rs:21. Typical: `import fs from 'fs'`, `import path from 'node:path'`, `import { promisify } from 'util'` in shared/browser code.","commonSituations":"Isomorphic packages where a server util leaked into client-shared code; pulling a small helper from a Node script into app code; SSR frameworks (Next.js) where some files run only server-side but the rule applies repo-wide.","solutions":["Swap to a browser-compatible alternative (e.g. node:path URL handling, Web Crypto instead of node:crypto, whatwg URL instead of node:url)","Split platform code: move the Node dependency behind a server-only module and import that instead","Add intentional exceptions to the allow list: `{ \"allow\": [\"node:path\", \"node:fs\"] }` for files that genuinely run on Node","Scope the rule to browser/shared directories via config overrides and leave server directories unchecked"],"exampleFix":"// before\nimport path from 'node:path';\nconst img = path.join(assetsDir, 'logo.png');\n\n// after\nconst img = new URL('./logo.png', import.meta.url).href;","handlingStrategy":"validation","validationCode":"// .oxlintrc.json\n{ \"rules\": { \"import/no-nodejs-modules\": [\"warn\", { \"allow\": [\"node:path\"] }] } }\n// browser-side pre-check: rg -n \"from\\\\s+['\\\"](node:)?(fs|path|crypto|util|os|child_process)['\\\"]\" src/client","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep server-only code in a separate directory and exclude it from this rule","Prefer Web-platform APIs (URL, Web Crypto, fetch) in shared code","When adding a Node builtin to shared utils, add it to the allow list consciously in the same commit"],"tags":["lint","oxlint","imports","nodejs","browser-compatibility","isomorphic"],"backgroundTag":"nodejs-builtin-in-browser-code","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}