Establish a package.json convention for Typescript source in monorepos and npm packages

[cefn]

Suggestion

Establish a convention for a field in package.json that will to point to Typescript source code, respected as an override by tsc, for IDE and downstream build tooling.

🔍 Search Terms

List of keywords you searched for before creating this issue. Write them down here so that others can find this suggestion more easily and help provide feedback.

exports typescript index.ts main source package.json

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

The tsc tool, through implementing and documenting a specific source import behaviour from package.json fields, could ensure that monorepo authors importing local packages and third-party bundlers importing upstream packages can resolve directly to Typescript source, while allowing package.json metadata to support publishing into the javascript ecosystem through "main", "module", "exports" independently (since they would always use distinct fields from the fields pointing to Typescript source).

Proposals for this new field could be...

• Introduce a convention for a field in exports[*]["import"] and exports[*]["require"] alongside "node", "browser", "default" e.g. a "typescript" or "source" field.
• Introduce a convention for a field in exports[*] alongside "import" and "require" - e.g. an "import:tsc" or "compile" field.
• Document and support that the top-level "types" field can be .ts and not just .d.ts, meaning it can serve both declarations and source
• Document and support that the top-level "source" field can point to .ts and that tsc see will see it as an override of "main", "module", entries in "exports"

📃 Motivating Example

In a monorepo, using a "main" field that resolves directly to a .ts path already allows direct resolution of source code. However, this interferes with the primary use case of the "main" field - to resolve Javascript. This then demands fragile prepublish and postpublish steps if "./src/index.ts" is to be rewritten to "./dist/index.js" and back again to fulfil the needs of a publish script. This suggests a distinct field needs to live alongside the Javascript resolution fields, allowing all elements to coexist and be individually addressable within the structure of a package.

💻 Use Cases

• Within a monorepo having multiple workspaces, they can have "main" or "exports" fields which point directly to Typescript files, allowing easy hot-reloading and eliminating the need for complex and fragile watches to fulfil e.g. transpiling to the CommonJS artefact pointed to by "main", or prepublish/postpublish scripts to rewrite "main".

• Within a downstream project that consumed an npm package following this convention (and including Typescript source) the downstream bundling process could consume source before it had been through any prior bundling process, minimising cruft and increasing the chances of adequate sourcemapping.

[cefn]

Possibly a duplicate of #21423 ?