{"record":{"id":"8d08b50084b44d7c","repo":"oxc-project/oxc","slug":"namespace-not-marked-type-only-declare-are-disable","errorCode":null,"errorMessage":"Namespace not marked type-only declare are disabled. To enable and review caveats see: https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support","messagePattern":"Namespace not marked type-only declare are disabled\\. To enable and review caveats see: https://oxc\\.rs/docs/guide/usage/transformer/typescript\\.html#partial-namespace-support","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_transformer/src/typescript/diagnostics.rs","lineNumber":37,"sourceCode":"        .with_label(span)\n        .with_error_code(\"TS\", \"1203\")\n}\n\n#[cold]\npub fn ambient_module_nested(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Ambient modules cannot be nested in other modules or namespaces.\")\n        .with_label(span)\n}\n\n#[cold]\npub fn namespace_exporting_non_const(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Namespaces exporting non-const are not supported by Oxc. Change to const or see: https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support\")\n        .with_label(span)\n}\n\n#[cold]\npub fn namespace_not_supported(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Namespace not marked type-only declare are disabled. To enable and review caveats see: https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support\")\n        .with_label(span)\n}\n","sourceCodeStart":19,"sourceCodeEnd":40,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_transformer/src/typescript/diagnostics.rs#L19-L40","documentation":"Oxc's TypeScript transform supports namespaces only partially, and this diagnostic fires when namespace compilation is switched off via `allowNamespaces: false` in TypeScriptOptions and a runtime (non-type-only) namespace is found. In `enter_program` of crates/oxc_transformer/src/typescript/namespace.rs:47-99, every top-level `TSNamespaceDeclaration`, `TSExternalModuleDeclaration`, `TSGlobalDeclaration`, and their `export`ed forms that lack the `declare` modifier gets `namespace_not_supported` (typescript/diagnostics.rs:37). Namespaces marked `declare` are treated as type-only and pass through cleanly. The default is `allow_namespaces: true` (typescript/options.rs:117), so this only appears for pipelines that explicitly opt out.","triggerScenarios":"Setting `allowNamespaces: false` (e.g. to match a strict Babel `allowNamespaces: false` config or to enforce namespace-free code) and transforming code containing `namespace Foo { export const x = 1; }`, `export namespace Foo { ... }`, `global { ... }`, or a non-declare `module Foo { ... }`. The guarded match at namespace.rs:69-76 explicitly excludes `declare`d declarations, so `declare namespace Foo {}` never warns.","commonSituations":"Teams adopting oxc-transform with a Babel-parity config where `allowNamespaces: false` was used to force erroring on legacy namespace code; monorepos where one shared config is applied to old library code still using namespaces; enabling the strict option to audit migration progress and hitting every legacy namespace in the build.","solutions":["If the namespace holds only types, mark it type-only: `declare namespace Foo { ... }` — declared namespaces are skipped and the warning disappears","Re-enable namespace support: set `allowNamespaces: true` (the default) and review the caveats at https://oxc.rs/docs/guide/usage/transformer/typescript.html#partial-namespace-support","Migrate the namespace away: convert to an ES module with named exports, or to a plain object/const for value grouping","Use `import type`/`export type` for type members and move runtime members into modules before re-enabling the strict option"],"exampleFix":"// before (allowNamespaces: false)\nnamespace Env {\n  export const PREFIX = 'app:';\n  export type Name = string;\n}\n\n// after\nexport const PREFIX = 'app:'; // env.ts module\nexport type Name = string;\n\n// or, if type-only:\ndeclare namespace Env { type Name = string; }","handlingStrategy":"validation","validationCode":"// If allowNamespaces is switched off, pre-scan for runtime namespaces\nconst allowNamespaces = tsOptions.allowNamespaces === true;\nfunction hasRuntimeNamespace(src: string): boolean {\n  return /^\\s*(export\\s+)?(?:namespace|module)\\s+\\w+\\s*\\{/m.test(src)\n    && !/^\\s*(export\\s+)?declare\\s+(?:namespace|module)\\s+/m.test(src);\n}\nif (!allowNamespaces && hasRuntimeNamespace(src)) {\n  throw new Error('runtime namespace found; mark it declare or migrate to modules');\n}","typeGuard":"// Config-level narrowing: only enable the strict mode on namespace-free trees\nfunction canDisableNamespaces(files: string[]): boolean {\n  return files.every(f => !hasRuntimeNamespace(read(f)));\n}\nconst tsOptions = canDisableNamespaces(srcs) ? { allowNamespaces: false } : { allowNamespaces: true };","tryCatchPattern":null,"preventionTips":["Only set `allowNamespaces: false` after a codemod removes runtime namespaces; otherwise keep the default true and read the partial-support caveats doc linked in the message","Mark type-only namespaces with `declare` so they survive even when the strict option is on","Track namespace usage in the repo (grep `^\\s*(export )?(namespace|module) \\w+`) as part of ESM-migration dashboards so flipping the option is a measured event, not a surprise"],"tags":["oxc","typescript","transformer","namespaces","config"],"backgroundTag":"typescript-namespace-unsupported","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}