`jsconfig.json` contrary to documentation implies `maxNodeModuleJsDepth: 2` etc #25

voxpelli · 2024-02-29T17:00:12Z

voxpelli
Feb 29, 2024
Maintainer

The only documentation of what additional rules jsconfig.json sets that I can find are the one in the VSCode docs, and it says (emphasis mine):

Tip: jsconfig.json is a descendant of tsconfig.json, which is a configuration file for TypeScript. jsconfig.json is tsconfig.json with "allowJs" attribute set to true.

But, turns out that it hasn't been true for 7.5 years. Here's a list of all additions on top of allowJs: true that has happened:

Aug 25, 2016: When maxNodeModuleJsDepth was changed to 0 as default for TS as a whole, it was kept as 2 for jsconfig.json (without updating the docs it seems) microsoft/TypeScript@c0309fa / Fix crash when checking module exports for export= microsoft/TypeScript#10538
Sep 23, 2016: allowSyntheticDefaultImports: true was added in microsoft/TypeScript@12578a5 / set allowSyntheticDefaultImports to true by default for jsconfig.json microsoft/TypeScript#11070
Oct 12, 2016: skipLibCheck: true was added in microsoft/TypeScript@460de66 / Turn on skipLibCheck for js-only inferred project and external project microsoft/TypeScript#11399
Jan 25, 2018: noEmit: true was added in microsoft/TypeScript@4af47f1 / Set noEmit = true on jsconfig.json file microsoft/TypeScript#21505

And that's where we remain today with jsconfig.json implying:

{
  "allowJs": true,
  "maxNodeModuleJsDepth": 2,
  "allowSyntheticDefaultImports": true,
  "skipLibCheck": true,
  "noEmit": true
}

It seems that the VSCode docs are long overdue for an update: https://github.com/microsoft/vscode-docs/blame/91835d57149c4352073c22300487a18baeefe13c/docs/languages/jsconfig.md#L18 (Which I will do following this post)

And likewise the documentation of maxNodeModuleJsDepth also needs to be updated:

Ideally this should stay at 0 (the default), and d.ts files should be used to explicitly define the shape of modules. However, there are cases where you may want to turn this on at the expense of speed and potential accuracy.

0 is not the default for jsconfig.json files, it defaults to 2.

And since maxNodeModuleJsDepth is only usable when allowJs is true it is quite likely that someone looking at that rule is also thinking about jsconfig.json.

Based on a realization in eslint/eslint#18100 (comment), initially posted as a comment in #2 (reply in thread)

voxpelli · 2024-02-29T17:13:58Z

voxpelli
Feb 29, 2024
Maintainer Author

TLDR is essentially: Don't use jsconfig.json, its an oddity that sets discouraged options like maxNodeModuleJsDepth without even documenting it.

That in turn can cause:

False errors – as shown by eg Bug: Types used in JSDoc blocks of @eslint/js are missing eslint/eslint#18100
Slow performance – as all the JS two levels down in maxNodeModuleJsDepth will get parsed if d.ts files are missing for them
Inconsistent type checking – if a module appears deeper down in node_modules than 2 steps, then it won't be picked up as maxNodeModuleJsDepth is only set to 2 (a sensible value for those cases where one need to use it, a case which existed before one could generate d.ts files from ones JSDoc comments, now that's the preferable solution)

Other defaults that can cause issues:

skipLibCheck – disables all type checking of d.ts files, not only the type checking of d.ts files in node_modules. That means that if you do write any d.ts files of your own in your project, the jsconfig.json defaults to disabling them. See issues it can cause here: Tests: Ensure that .d.ts files are checked by setting skipLibCheck: false sindresorhus/type-fest#785 And me choosing to have it disabled here: Remove skipLibCheck tsconfig#1

Worth noting:

allowSyntheticDefaultImports – will already be default when "module": "node16" or "module": "nodenext", something most JS-projects should have set anyways (and something I have in my base config). It's also active in eg @tsconfig/recommended as it sets esModuleInterop which in turns sets allowSyntheticDefaultImports and "module": "node16" or "module": "nodenext" sets esModuleInterop

Options that the default doesn't set and which you should set:

strict – always always always set strict: true

For more suggestions, see my base config, which also links to other base configs: https://github.com/voxpelli/tsconfig My base config is set up purely for a types in JS workflow (backed up by occasional manual d.ts)

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

`jsconfig.json` contrary to documentation implies `maxNodeModuleJsDepth: 2` etc #25

{{title}}

Replies: 1 comment

{{title}}

Select a reply

jsconfig.json contrary to documentation implies maxNodeModuleJsDepth: 2 etc #25

voxpelli Feb 29, 2024 Maintainer

Replies: 1 comment

voxpelli Feb 29, 2024 Maintainer Author

`jsconfig.json` contrary to documentation implies `maxNodeModuleJsDepth: 2` etc #25

voxpelli
Feb 29, 2024
Maintainer

voxpelli
Feb 29, 2024
Maintainer Author