installing typedoc is forcing the use of 'dom' in `tsconfig.json.compilerOptions.lib`

[zam6ak]

I have a "pure" Node lib for which I wanted to use typedoc to generate documentation...
After installing it and running it I started getting this error:

node_modules/@types/highlight.js/index.d.ts(19,40): error TS2304: Cannot find name 'Node'.

After some googling I found this issue explaining that one of typedoc dependencies (highlight.js) requires 'dom' being in the list of libs for typescript compiler...

Is there a way for me to use typedoc on a pure node library without having to resort to including 'dom' in typescript?

[lddubeau]

I've added a typedoc execution to the gulpfile of a library of mine just yesterday. The library does not depend on the DOM being present and can run in Node or the browser so it does not list dom in its lib. I can run typedoc just fine. I never ran into the issue you report, nor did I have to take special care to avoid it in the first place.

Providing a MCVE/SSCCE/MWE, would help zero in on the problem you actually ran into.

[mnpenner]

I'm encountering this issue too. @lddubeau Did you install typedoc as a dev dependency? If you do that, it adds node_modules/@types/highlight.js which seems to cause tsc to always use it, which breaks my compile.

[blakeembrey]

Yeah, this is really unfortunate. Also unfortunately, the TypeScript team has been specific about not supporting multiple type definitions for browser vs node.js. This is the use-case I had with Typings that has since gone away with adopting NPM @types (at least until TypeScript implements something new). You can bring it up here: microsoft/TypeScript#7753. There's also some other potential solutions available such as compiler controlled regions in the issues proposed by various people, but I don't think there's any solution available today.

[mnpenner]

@blakeembrey Just found a solution actually. There's a compiler option called "types" which lets you be explicit about which type definitions to include, instead of including everything under node_modules/@types as it does by default. It's unfortunate that we have to explicitly list them out, but I can at least compile my project again!

[blakeembrey]

@mnpenner That makes sense! It only works so long as TypeDoc never accidentally exports a type from one of these packages though. Right now the imports are elided from the .d.ts files when they aren't used, but in the case where they aren't - it'll be a real issue with no hack around it (because TypeScript will resolve it using regular module resolution).

[lddubeau]

@mnpenner I have typedoc installed as a dev dependency, but looking again at my configuration I found why I'm not getting the error. I have skipLibCheck: true. If I remove it, then I get the error.

[mnpenner]

Actually I can get my project compiling now, but I can't can't get typedoc working now. It's just spewing out dozens of random errors. I think I'm going to give up on it.

[JoshuaKGoldberg]

Simpler solution: how about highlightjs just provide a stub interface Node { }?

Alternately, why do the @types modules need to be dependencies? Can they be changed to devDependencies?

[aciccarello]

@JoshuaKGoldberg The @types system has some flaws but we need to put them in the dependencies for the reasons specified in many other issues (see #408 #335 #350 #384 #418 and #434). As far as stubbing the node definition, I'm not sure that's a pattern the DefinitelyTyped repo wants to follow.

[nikeee]

Maintainer of the highlight.js definition here.
I think it's not the best solution to patch the definitions of highlight.js. I came up with a solution on the library user's side:
https://gist.github.com/nikeee/5a46d1ff4ea7bbb088817740f7376009

Would this work for you?

[JoshuaKGoldberg]

@nikeee that sounds good! I'll send a PR to the definition thanks!

Oh, just re-read your comment+gist: you're proposing consumers of the highlight.js types should do that?

If so, no - that doesn't work ☹️. highlight.js is meant to work in pure Node environments, such as with jsdom (which is a dev dependency in highlight.js' package.json). It shouldn't have a dependency on the "dom" lib in TypeScript. If there is a dom dependency in the types, that implies the project has a dependency on the dom to operate. See this issue and others in the repo that mention jsdom.

Since highlight.js exposes a highlightBlock method that takes in a block parameter of type Node, the proper thing for it to do would be to describe exactly what's expected of that. That can be done by manually specifying all the fields that happen to exist on both that block: Node and the standard DOM node... but that's a lot of work to create and maintain. So I think it's very reasonable to improve the typings to just use a stub Node interface that'll be filled out when used in a dev environment with dom types.