API Extractor and TypeScript guide for ts-node users #222
Conversation
|
@ajvincent thanks for contributing these docs! 👍 |
|
|
||
| ## Copying existing type declaration files | ||
|
|
||
| You're not done yet. TypeScript converted your `**.ts` files to `**.d.ts`, but it didn't migrate your _existing_ type declaration files. You need to do that yourself. |
There was a problem hiding this comment.
Sounds like the observation here is that tsc normally does not copy .d.ts files from src to lib, when it is transpiling src/*.ts to produce lib/*.d.ts. Normally such .d.ts files should either be stored in a relative folder (e.g. ../typings/*.d.ts) or else the toolchain can copy them. By "toolchain", I mean that mature projects generally do not build using a shell command like tsc && eslint && jest && api-extractor -- instead they will use a standard CLI that can intelligently chain these tasks, cache the results, and support interactive watch mode. (The Rush Stack toolchain is Heft.)
By contrast, the ts-node is aimed at lightweight scripting scenarios, where the user wants to execute .ts files directly without any build process or configuration. Instead of running node script.js, you can run ts-node script.ts that merely adds basic type checking and nothing else.
But as you observed, this simplistic approach causes trouble when trying to integrate with other stages like API Extractor. When such requirements arise, the typical solution would be to switch to using a proper toolchain. The code snippets here are basically starting down that path -- this script invokes tsc, then copies over the .d.ts files, then invokes API Extractor. (Oh and it probably should copy .json files as well. And oh it probably needs a way to clean them. Which means the CLI needs a --clean parameter, so really we should have --help, etc. Wait a second, why not just use a real toolchain again? 😄 )
It feels like it's drifting away from the premise of ts-node, which to avoid a build process. Thus I wonder if it might be more fruitful to implement a simple NPM package like ts-node-api-extractor that combines these ideas into a simple command line. It would:
- Read the real *tsconfig.json
- In memory, magically add the
declaration,emitDeclarationOnly, andoutDirsettings - Then invoke
tscto produce *.d.ts files in a temporary directory - Copy over the *.d.ts inputs
- Then invoke API Extractor on the output
Basically just package up all this code so that a person who uses ts-node can generate their .d.ts rollup or .api.md report without having to configure anything. What do you think?
There was a problem hiding this comment.
Wait a second, why not just use a real toolchain again? 😄
Because I built this incrementally and slapped API Extractor in later? 😁 But your point is extremely well-taken. It could be a form of technical debt I've built up in my project. At some point, maybe I should do that conversion and this PR should be turned away - or into a "here's why you should convert to a toolchain" article.
I have no problem throwing away code or ideas that are less efficient.
Basically just package up all this code so that a person who uses ts-node can generate their .d.ts rollup or .api.md report without having to configure anything. What do you think?
Two catches. One, I had to do some massaging of the generated type definition files before I could feed it to API Extractor. So such a package would need to include a hook script option for that purpose.
Two, and I really believed this would've been fixed by now, ts-node has stopped working out-of-the-box on NodeJS 18.19+. Various people have suggested five to seven solutions, again and again. Most of those solutions are "move off of ts-node, here's a similar project that works". It's really quite disheartening. This is another reason I'm rethinking the home-grown build system I've already got in place in my project. I had looked at both Grunt and Gulp, and turned them down - one for vulnerabilities, one for ESM incompatibility.
I've been on a bit of a break from my project since I released version 1.0 a couple weeks ago.
There was a problem hiding this comment.
Well stepping back and thinking about this, I suppose my hesitation with this doc is that it includes enough interesting code that people will want to complete the code sample, and code review it, and improve it over time, which is difficult to do in an .md page. If you don't have time to maintain a new GitHub project yourself, another idea would be to contribute it to the Rush Stack repo as a rushstack-samples or build test project. (We'd also be onboard with building something like this directly into API Extractor, a mode where it invokes tsc automatically into a temp folder to produce the .d.ts inputs -- but that is probably an even bigger time commitment. 😄)
Anyway you can think about the best way to go. There's no hurry.
No description provided.