JSConfig / TSConfig

[Raynos]

To get the most out of leveraging jsdoc you want to configure your project.

In my experience, I found that a jsconfig.json file behaves better then a tsconfig.json file.

I have an example jsconfig.json file

{
  "extends": "./types/base-tsconfig.json",
  "compilerOptions": {
    "baseUrl": "./",
    "paths": {
      "@pre-bundled/tape": ["./types/pre-bundled__tape"],
      "@pre-bundled/rimraf": ["./types/pre-bundled__rimraf"],
      "*" : ["./types/*"]
    }
  },
  "include": [
    "types/**/*.d.ts",
    "node_modules/tape-harness/index.js",
    "index.js",
    "test/**/*.js"
  ]
  // "exclude": ["node_modules"]
}

For my personal sanity I choose to put some defaults in another file. I copy that file into basically every project and it's very similar and not project specific ( https://github.com/Raynos/fake-s3/blob/master/types/base-tsconfig.json ).

The content of the jsconfig.json is project specific and it states the files and dependencies for this project.

[voxpelli]

I for a long while didn't know about jsconfig.json, so I've stuck with tsconfig.json as the only difference except for the name that I know of is that jsconfig.json implies allowJs: true.

My typical tsconfig.json right now looks like:

{
  "files": [
    "index.js"
  ],
  "include": [
    "lib/**/*.js",
    "test/**/*.js"
  ],
  "compilerOptions": {
    /* Basic Options */
    "target": "ES2017",
    "lib": ["ESNext.Array"],
    "module": "commonjs",
    "allowJs": true,
    "checkJs": true,
    "resolveJsonModule": true,
    "noEmit": true,
    "esModuleInterop": true,

    "removeComments": true,

    /* Strict Type-Checking Options */
    "strict": true,
    "noImplicitThis": true,
    "noImplicitAny": true,
    "strictNullChecks": true,

    /* Additional Checks */
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true
  }
}

I will eventually move to the setup of eg. @sindresorhus, with an extracted config that's shared between all of my projects: https://github.com/sindresorhus/tsconfig

I have so far felt that I'm still in a state of iteration and that such an abstraction for me would still be a bit premature. But eventually I will make a @voxpelli/tsconfig module.

[voxpelli]

I have now moved to such an extracted config, and I opted to do so similar to how TypeScripts own base configs are: https://github.com/tsconfig/bases

So I eg. have both a node14.json and a node12.json: https://github.com/voxpelli/tsconfig

[Raynos]

Do you have a usage examples ?

[voxpelli]

Here’s one: https://github.com/voxpelli/node-pg-pubsub/blob/main/tsconfig.json

[Raynos]

so I've stuck with tsconfig.json as the only difference except for the name that I know of is that jsconfig.json implies allowJs: true.

I've found that there are subtle differences in way the text editor behaves in the existance of a tsconfig / jsconfig file. The existance of a tsconfig file with no typescript files can make the editor behave less javascript friendly.

[voxpelli]

Interesting, any particular ways you can remember where it behaves less friendly? Maybe I should make the switch.

[Raynos]

Go to definition behaves differently based on jsconfig / tsconfig. The existance of a tsconfig.json breaks go to definition.

microsoft/TypeScript#40978

[voxpelli]

Worth mentioning in this context: #6 (comment)

@Raynos Thoughts on jsconfig in relation to that?

[voxpelli]

Seems like jsonfig.json nowadays implies much more than just the allowJs: true that the VSCode docs implies: eslint/eslint#18100 (comment)

[voxpelli]

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
}

But the only documentation of what it implies that I can find is the one in VSCode docs, and those say:

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.

It seems long overdue for an update: https://github.com/microsoft/vscode-docs/blame/91835d57149c4352073c22300487a18baeefe13c/docs/languages/jsconfig.md#L18

(Which I will do following this comment)

[voxpelli]

Separated into a new post: #25

TLDR is essentially: Don't use jsconfig.json, its an oddity that sets weird options.