Module documentation tracking issue

[andrewbranch]

I’m working on new documentation for modules in TypeScript. I’ll use this issue to track progress. Related:

• What’s confusing about modules? #51876
• Guidance needed: how to configure tooling to use .js file extension in TypeScript imports #52412
• Fix documentation that seems to imply baseUrl does something it doesn't #51267

[andrewbranch]

Proposed, very ambitious outline, subject to change:

1. Introduction
   1. Who is this for?
2. Theory
   1. Scripts and modules in JavaScript
   2. What is TypeScript’s job concerning modules?
   3. Module emit
      1. Input syntax is (somewhat) decoupled from output
      2. Note: verbatimModuleSyntax
      3. Note: top-level await
      4. Module format interop
      5. Module specifiers are not transformed
   4. Module resolution
      1. Module resolution is host-defined
      2. Who is the host?
      3. TypeScript “mirrors” the host resolver
         1. Module specifiers reference the host’s source files
         2. Declaration files are substituted for JS files
         3. Note: non-JS files supported with allowArbitraryExtensions
      4. Common resolution features
         1. Omittable extensions and directory index files
         2. node_modules and package.json
            1. @types
            2. package.json "exports"
      5. Node’s dual-algorithm system
         1. CJS/ESM detection
            1. File extensions
            2. package.json "type"
         2. ESM algorithm restrictions
         3. package.json "exports" conditions
         4. Importing ESM from CJS requires dynamic import
      6. Bundlers and other Node-like non-Node hosts
         1. noEmit and allowImportingTsExtensions
         2. Customization options
   5. Caveats / limitations?
      1. Why module specifiers are not transformed
      2. Why dual-emit is not supported and sometimes impossible
      3. Future work? Browser, import maps, URLs?
3. Guides
   1. Choosing compiler options
   2. Troubleshooting dependency issues
   3. Publishing a library
4. Reference
   1. Module syntax
      1. ESM (link elsewhere?)
      2. CJS in JavaScript
      3. CJS in TypeScript
      4. Type-only imports and exports
      5. Ambient module declarations & augmentations?
   2. Module emit and checking
      1. module
         1. commonjs
         2. es2015+
         3. node16/nodenext
      2. CJS/ESM interop details
      3. The default problem
      4. __esModule marker
      5. allowSyntheticDefaultExports
      6. esModuleInterop
      7. verbatimModuleSyntax
   3. Module resolution
      1. moduleResolution
         1. node16/nodenext
         2. bundler
      2. allowJs and maxNodeModuleJsDepth
      3. package.json
         1. "main", "types"
         2. "typesVersions"
         3. "exports"
         4. "type"
         5. "imports"
      4. Customization compiler options
         1. paths
         2. baseUrl
         3. resolvePackageJsonImports
         4. resolvePackageJsonExports
         5. customConditions
         6. allowImportingTsExtensions
         7. resolveJsonModule
         8. rootDirs
         9. typeRoots
         10. moduleSuffixes

[fatcerberus]

Who is this for?

Approximately everybody 😄

[RyanCavanaugh]

Another section we'll need is effectively "What is the right thing to put on DefinitelyTyped?"

[DanielRosenwasser]

What module settings should my new project use?

[andrewbranch]

@DanielRosenwasser please refer to section 3.i

[fatcerberus]

What module settings should my new project use?

All of them

[jmrossy]

@andrewbranch Two more fields worth covering in 4.iii.c:
module and browser

[robpalme]

I'm not sure which section this would go in, but there is a semi-obscure question/choice I'd like to get an authoritative answer on, so I'm kinda hijacking this issue as a place to resolve it.

Question

• Is it legitimate for a project to store hand-written utility types in a local *.d.ts source file instead of using a *.ts source file?

It's common to have local files in which you might store utility types. Maybe you put them in a directory called util-types/. So which file extension type should you put in this directory?

• A full-fat *.ts file would work, but at best will result in an empty *.js file being emitted, and at worst might deviate from programmer intent over time if someone accidentally inserts value-land code.
• Whereas a *.d.ts enforces this intent and guarantees to have zero JS emit - it only is needed during checking.

Here's some example usage in a multi-file playground.

// @filename: index.ts
import type { Point } from "./util-types/only-types"
export const location: Point = {
    x: 0,
    y: 0,
}

// @filename: util-types/only-types.d.ts
export interface Point {
    x: number,
    y: number,
}

Potential Answers

I'm looking for a steer on whether the use of *.d.ts files for storing hand-written utility types is:

1. Encouraged: because this style has active benefits
2. Supported: but there's no value judgement on which style you should pick
3. Discouraged: this style is supported and not going away, but may confuse people
4. Harmful: it may seem to work but will hurt you later or might be deprecated

The answer will help inform whether we should internally force the use of *.ts files for this purpose by banning hand-written *.d.ts files.

[andrewbranch]

The answer to this question is unsatisfying to me. I would say it’s discouraged or even harmful (though it won’t be “deprecated”). At best, it’s a technique with serious pitfalls that can be leveraged by people who understand them enough to set up additional tooling and safeguards to make it viable. Because .d.ts files only occur “naturally” as a pair with a .js file, together as outputs of a .ts file, a .d.ts file always implies the existence of a .js file. So the potential harm is readily apparent: if you hand-author only-types.d.ts and then write import {} from "./only-types.js", this resolves and is legal in all settings, but in verbatimModuleSyntax, the import will be preserved and crash at runtime. While TypeScript has type-only imports and exports, it lacks the analogous concept of a type-only module, one which exists for type information purposes but is known to not exist at runtime, though I’ve casually suggested multiple times that such a concept could be useful.

But the main reason I personally avoid this is just because it doesn’t copy into outDir. For my purposes, I’d rather just eat the cost of the empty JS file (which also protects you from crashes should you accidentally import it at runtime).