publishing deep-dive is out of date regarding "exports"

[jason-ha]

Page URL: https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html

publishing.html mentions "types" and "typings" fields but there are no comments about "exports" which I believe can supersede those. And I think they do not apply when there is a subpath based on documentation from https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-main-and-types.

https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-exports has good information about resolving; so, one could work backward if just given a reference there. But specific guidance on authoring is probably best.

"typings" is listed as an alias on publishing.html but is noted as legacy on modules/reference.html.

[agilgur5]

The lack of updates on this page is indeed very confusing for library developers. Just ran into this issue twice in taybenlor/runno#324 and agilgur5/react-signature-canvas#126.

but there are no comments about "exports" which I believe can supersede those. And I think they do not apply when there is a subpath based on documentation from https://www.typescriptlang.org/docs/handbook/modules/reference.html#packagejson-main-and-types.

Indeed, if you have exports, you must define types inside of exports (e.g. exports.types). Per TS maintainers in microsoft/TypeScript#52363 (comment) and microsoft/TypeScript#46334, TS will not fallback to the top-level types when exports is defined. Those maintainer comments have been referenced a lot and are buried in TS issues -- there really should be clear, direct, official guidance in the official docs.
One of the maintainers also created https://github.com/arethetypeswrong/arethetypeswrong.github.io as a website and CLI to diagnose this -- would be nice to add that to the docs too.

There are also some docs buried in the 4.7 release notes.

Matching the intent of the "Publishing" page, I think specific, centralized publishing guidance would be better and would significantly reduce confusion.

"typings" is listed as an alias on publishing.html but is noted as legacy on modules/reference.html.

I tested this and typings does not work inside of exports. You cannot use exports.typings and must use exports.types (or deeper structures -- the naming is the key difference, literally).
As such, for consistency and less mistakes, it would make sense to migrate top-level typings to types as well and only mention this as a legacy alias that should not be used moving forward.