Deprecate skipLibCheck and introduce skipDeclarationErrors

[thernstig]

🔍 Search Terms

• skipLibCheck
• skipLibCheck exclude
• skipLibCheck skipDeclarationErrors

#30511 is relevant here.

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

skipLibCheck should be deprecated and a new skipDeclarationErrors should takes it place, taking precedence if configured.

skipLibCheck is confusing for two reasons (taken from here):

• “Skip lib check” suggests that only library-related code will be skipped. This isn’t true – d.ts files that are part of the project will be affected too.
• d.ts files aren’t really skipped entirely. As shown in the demo project, valid types coming from d.ts files are never skipped.

When doing this, https://www.typescriptlang.org/tsconfig#skipLibCheck (or the new https://www.typescriptlang.org/tsconfig#skipDeclarationErrors) should be updated to highlight the impoprtant findings listed on https://www.testim.io/blog/typescript-skiplibcheck/.

📃 Motivating Example

Coming from a developer experience (DX) perspective, I have found one of the hardest things about TypeScript is its configuration options and its documentation. There is a lot to be said, but in general having setup tens and tens of linters, formatters and similar in various languages, TypeScript has been one of the hardest to understand.

There are two big reasons for this:

• Declarative configuration for tools should have clear identifiers and nomenclature. This is not the case with skipLibCheck which throws you off.
• The current description is incomplete at https://www.typescriptlang.org/tsconfig#skipLibCheck, as apparent from the above suggestions and caveats from https://www.testim.io/blog/typescript-skiplibcheck/. Updating the documentation for this could be done standalone, but I believe the best long-term path would be also rename the identifier.

In general there is a lot of good documentation for TypeScript on https://www.typescriptlang.org/docs/. However, it often feels like the config options to setup a project has fallen behind. This is apparent of the hundreds/thousands of SO questions.

💻 Use Cases

1. I want to use this to signal to future readers what is really being done by setting this option.

[fatcerberus]

Skip type checking of declaration files.

Leaving aside the name of the option (which I agree could be better), the documented behavior above seems pretty clear to me - it doesn't typecheck the .d.ts files themselves, that doesn't mean the file is completely skipped over, and it can still check types that come from them if used in code (i.e. the types still mean something even if they're not checked in situ).

IMO the option wouldn't be very useful if it meant any type coming from a .d.ts file got treated as an effective any.

[RyanCavanaugh]

Fundamentally, this feature doesn't make sense unless you read the docs (which, yes, probably could be clarified further). No 20-character description of it is going to capture all the nuance and renaming it will just introduce further questions of why they're different, why I have to update my config file for literally no reason, etc.

[thernstig]

The suggestion comes from a holistic standpoint for the options. Something that comes from the path many tools take to long-term improve. It is not uncommon at all for renames to create a longer-term wins. I wish the mindset was the same here. As a great example, VS Code does this quite often for its settings.

No 20-character description of it is going to capture all the nuance and renaming it will just introduce further questions of why they're different, why I have to update my config file for literally no reason, etc.

That is true for a transition period, but not long-term.

Leaving aside the name of the option (which I agree could be better), the documented behavior above seems pretty clear to me - it doesn't typecheck the .d.ts files themselves, that doesn't mean the file is completely skipped over,

It is not clear to everyone. It is obvious from the above blog post and many SO questions. In fact, it is wrong, as shown in the original post. You are talking about semantics on what "skip type checking" means. tsc obviously reads the file, so is the types skipped? That is the entire point of both the rename and description, to be more explicit about this, which should be entirely possible.

[fatcerberus]

so is the types skipped?

No, type checking of that file is skipped, which is exactly what the documentation says it will do. I’m not sure how you got from that to “all processing of the contents of this file is skipped” - it wouldn’t be useful if you couldn’t still use those types in files that are checked, in fact that would be even more confusing - i.e. “Why are some of my type annotations being ignored?”

[RyanCavanaugh]

I'd consider a rename in the case that the new name was unambiguously better, but this just isn't. skipDeclarationErrors has confusion as well: You'd still get errors in declare constructs in .ts files, and it's not accurate either because we're not skipping the errors, we're skipping the checking, which are not technically the same thing.

[typescript-bot]

This issue has been marked as "Declined" and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[thernstig]

I understand. The suggested name is not the best, but the current one is not great either and I would have hoped something better could come out of the discussion, but maybe not.

so is the types skipped?

No, type checking of that file is skipped, which is exactly what the documentation says it will do. I’m not sure how you got from that to “all processing of the contents of this file is skipped” - it wouldn’t be useful if you couldn’t still use those types in files that are checked, in fact that would be even more confusing - i.e. “Why are some of my type annotations being ignored?”

I am not sure how to convey the gist of this discussion better. It is not clear. "But it is clear to me" does not mean everyone. We could argue people are dumb, not reading it verbatim etc. "Skip type checking of declaration files." will be read by some as "oh, it will skip the file". There is cause for confusion, with all rights, for this, no matter how correct one thinks that sentence is.

This could be improved easily, removing this ambiguity, something like this, using your own wording (this should be improved, it is not perfect):

Skip type checking of declaration files. It does not type check the .d.ts files themselves, but the files are still read by the parser and it can still check types that come from them if used in code.

This entire discussion is a bit frustrating in a sense. When it comes to writing technical documentation, one of the biggest mistake users do that has knowledge about the project at hand is to take for granted people "are not reading the documentation properly". When as the above discussion shows, as well as https://www.testim.io/blog/typescript-skiplibcheck/ and hundreds more Google results about this, shows it is not clear. This is not at fault of users reading the docs, it is the docs.

I wish at least the issue at hand could have been accepted as a way to accept a PR to try to improve the doc, which I would be willing to try given the feedback in here.

[RyanCavanaugh]

Doc PRs are fine, no objection there