In a typical TypeScript module, you will find a 'src' directory containing TypeScript source code files. The module compiles these sources using 'tsc -d --outDir dist' to create the 'dist' directory and sets specific package metadata to ensure compatibility with both Node.js runtime and TypeScript compiler.
{
"main": "dist/index.js",
"types": "dist/index.d.ts",
"files": ["dist"]
}
Adding source-maps and original source code to packages can facilitate debugging.
Considering the introduction of Project References and the compiler option '--declarationMap', it is recommended for modules to provide declaration map files as well. This allows IDEs to navigate from module API calls directly to the implementation, rather than just the generated '.d.ts' files.
Thus, a module is expected to contain:
- Transpiled '.js' files for runtime
- Original '.ts' files for debugging
- Declaration files '.d.ts' for TypeScript compiler
- Declaration map files '.d.ts.map' for IDE tooling
However, the complexity of this setup raises the question - what if we eliminate '.d.ts' and '.d.ts.map' files and ship the original TypeScript sources instead?
{
"main": "dist/index.js",
"types": "src/index.ts",
"files": ["src", "dist"]
}
Some potential downsides to this approach include:
Increased workload for TypeScript compiler when compiling projects dependent on the module, as it needs to parse full '.ts' sources instead of concise '.d.ts' files, potentially resulting in slower builds.
Similar impact on IDEs like VSCode, which would need to parse full '.ts' sources instead of optimized '.d.ts.map' files for faster processing.
Additionally, there is a distinction between '.d.ts' and '.ts' files - the former exports declarations only, while the latter exports definitions. It raises questions about how TypeScript handles multiple instances of the same module within the dependency tree.
Considering these factors, are there any valid arguments against using original '.ts' files for type declarations?