Skip to content

docs(declaration-files): document implicit export visibility in .d.ts modules#3615

Open
milcho0604 wants to merge 1 commit into
microsoft:v2from
milcho0604:docs/dts-implicit-export-visibility
Open

docs(declaration-files): document implicit export visibility in .d.ts modules#3615
milcho0604 wants to merge 1 commit into
microsoft:v2from
milcho0604:docs/dts-implicit-export-visibility

Conversation

@milcho0604

Copy link
Copy Markdown

Summary

Adds a section to the declaration-files Deep Dive page documenting a
long-standing but undocumented behavior: in a module .d.ts file, all
top-level declarations (types and values) are importable from outside the
module even without the export keyword, and appending export {} opts back
into normal only-explicit-exports visibility.

This is the behavior discussed in microsoft/TypeScript#32182 (open since 2019,
labeled Docs), where it was noted that the handbook doesn't mention it.

Why

I hit this while adding a type-export test to a library PR: a compile-only
test cannot assert the export keyword on a .d.ts type, because removing
export still type-checks for consumers. The behavior is by design, but
nothing in the handbook says so — the Deep Dive page seemed like the natural
home, since it already covers declaration-file name resolution.

All claims verified against TypeScript 5.9.3:

Case Result
.ts module, import non-exported type error TS2459
.d.ts module, import non-exported type OK (no error)
.d.ts module, import non-exported declare const / declare class OK (no error)
same .d.ts with export {} added error TS2459

The runtime caution was also verified on Node.js: importing a binding that the
underlying JS module doesn't export throws at load time under ESM and yields
undefined under CommonJS interop.

Notes

  • Pure addition at the end of the page; no existing content changed.
  • Wording follows the page's existing style ("Say we have a module file
    foo.d.ts… Then consumed it:").

Refs microsoft/TypeScript#32182

… modules

All top-level declarations in a module .d.ts file (types and values) are
importable from outside even without the export keyword, and appending
'export {}' opts back into only-explicit-exports visibility. This behavior
is by design but was not covered in the handbook.

Refs microsoft/TypeScript#32182
@milcho0604

Copy link
Copy Markdown
Author

@microsoft-github-policy-service agree

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant