{"record":{"id":"914e26e92549d644","repo":"oxc-project/oxc","slug":"es2015-module-syntax-is-preferred-over-namespaces","errorCode":null,"errorMessage":"ES2015 module syntax is preferred over namespaces.","messagePattern":"ES2015 module syntax is preferred over namespaces\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/typescript/no_namespace.rs","lineNumber":16,"sourceCode":"use oxc_ast::AstKind;\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\nuse schemars::JsonSchema;\nuse serde::Deserialize;\n\nuse crate::{\n    AstNode,\n    context::{ContextHost, LintContext},\n    rule::{DefaultRuleConfig, Rule},\n    utils::has_ambient_typescript_ancestor,\n};\n\nfn no_namespace_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"ES2015 module syntax is preferred over namespaces.\")\n        .with_help(\"Replace the namespace with an ES2015 module or use `declare module`\")\n        .with_label(span)\n}\n\n#[derive(Debug, Clone, JsonSchema, Deserialize)]\n#[serde(rename_all = \"camelCase\", default, deny_unknown_fields)]\npub struct NoNamespace {\n    /// Whether to allow declare with custom TypeScript namespaces.\n    ///\n    /// Examples of **incorrect** code for this rule when `{ \"allowDeclarations\": true }`\n    /// ```typescript\n    /// module foo {}\n    /// namespace foo {}\n    /// ```\n    ///\n    /// Examples of **correct** code for this rule when `{ \"allowDeclarations\": true }`\n    /// ```typescript\n    /// declare module 'foo' {}","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/typescript/no_namespace.rs#L1-L34","documentation":"Diagnostic from oxlint's port of @typescript-eslint/no-namespace. Custom TypeScript namespaces (`namespace Foo {}`) predate ES2015 modules and produce runtime objects + harder tree-shaking, so the rule reports namespace declarations in normal code and recommends ES module syntax (or `declare module` for ambient typing). Options: `allowDeclarations` permits `declare namespace`, and definition files (.d.ts) can be exempted.","triggerScenarios":"A `namespace X { ... }` declaration in a non-declaration file (or a `declare namespace` when allowDeclarations is false). The rule consults `has_ambient_typescript_ancestor` to skip ambient contexts; module augmentation and `declare module 'name'` forms are the recommended alternatives per the help text.","commonSituations":"Legacy codebases from pre-ES2015-module days; namespace used as a bundling/organization device inside one file; global type pollution via namespaces; migrating internal modules to `import`/`export` during a modernization.","solutions":["Convert the namespace to an ES module: move members to a file, `export` them, `import` at use sites.","For pure typing, use ambient declarations: `declare module 'x'` or `declare namespace` with `\"allowDeclarations\": true`.","Enable `\"allowDefinitionFiles\": true` if .d.ts files legitimately need namespaces.","For a wrapped-value pattern (namespace as object literal), replace with a plain exported const object."],"exampleFix":"// before: MathUtils.ts\nnamespace MathUtils {\n  export const add = (a: number, b: number) => a + b;\n}\n// consumer: MathUtils.add(1, 2);\n\n// after: MathUtils.ts\nexport const add = (a: number, b: number) => a + b;\n// consumer: import { add } from './MathUtils'; add(1, 2);","handlingStrategy":"validation","validationCode":"oxlint --ts-plugin src/ # no-namespace; allowDeclarations/allowDefinitionFiles per config","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Model code organization with ES modules (export/import) and directories, not namespaces.","Keep genuinely ambient typing in .d.ts files with declare module/declare namespace and enable allowDeclarations+allowDefinitionFiles.","During migration, convert one namespace per PR and let the rule block new ones."],"tags":["typescript","namespace","modules","modernization","oxlint","lint"],"backgroundTag":"typescript-namespace-usage","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"}