oxc-project/oxc · warning · OxcDiagnostic

Namespace not marked type-only declare are disabled. To enab

Error message

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

What it means

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.

Source

Thrown at crates/oxc_transformer/src/typescript/diagnostics.rs:37

        .with_label(span)
        .with_error_code("TS", "1203")
}

#[cold]
pub fn ambient_module_nested(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Ambient modules cannot be nested in other modules or namespaces.")
        .with_label(span)
}

#[cold]
pub fn namespace_exporting_non_const(span: Span) -> OxcDiagnostic {
    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")
        .with_label(span)
}

#[cold]
pub fn namespace_not_supported(span: Span) -> OxcDiagnostic {
    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")
        .with_label(span)
}

View on GitHub (pinned to e1e7af627c)

Solutions

1. If the namespace holds only types, mark it type-only: `declare namespace Foo { ... }` — declared namespaces are skipped and the warning disappears
2. 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
3. Migrate the namespace away: convert to an ES module with named exports, or to a plain object/const for value grouping
4. Use `import type`/`export type` for type members and move runtime members into modules before re-enabling the strict option

Example fix

// before (allowNamespaces: false)
namespace Env {
  export const PREFIX = 'app:';
  export type Name = string;
}

// after
export const PREFIX = 'app:'; // env.ts module
export type Name = string;

// or, if type-only:
declare namespace Env { type Name = string; }

// If allowNamespaces is switched off, pre-scan for runtime namespaces
const allowNamespaces = tsOptions.allowNamespaces === true;
function hasRuntimeNamespace(src: string): boolean {
  return /^\s*(export\s+)?(?:namespace|module)\s+\w+\s*\{/m.test(src)
    && !/^\s*(export\s+)?declare\s+(?:namespace|module)\s+/m.test(src);
}
if (!allowNamespaces && hasRuntimeNamespace(src)) {
  throw new Error('runtime namespace found; mark it declare or migrate to modules');
}

// Config-level narrowing: only enable the strict mode on namespace-free trees
function canDisableNamespaces(files: string[]): boolean {
  return files.every(f => !hasRuntimeNamespace(read(f)));
}
const tsOptions = canDisableNamespaces(srcs) ? { allowNamespaces: false } : { allowNamespaces: true };

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Namespaces exporting non-const are not supported by Oxc. Cha
• TS1202
• TS1203
• Ambient modules cannot be nested in other modules or namespa
• The description for the @ts-{ts_comment_name} directive must

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/8d08b50084b44d7c. Report an issue: GitHub.