Feature Request: allow exclusion of node_modules when skipLibCheck is false

Search Terms

skipLibCheck node_modules, skipLibCheck

All I've found is this lonely SO post. As that user notes, there are a lot of posts around Angular and excluding node_modules from typechecking on one dimension or another, but they all end up suggesting turning on skipLibCheck.

Suggestion

Allow the exclusion of files in node_modules (regardless of their inclusion in the Project) from lib checking when skipLibCheck is set to false.

Use Cases

I want to be able to typecheck my own .d.ts files without being responsible for all of the types my dependencies import. My local configuration is strict and it may be that the types provided in my packages were not intended strictly, or other configurations in my local JSON run up against the way other packages have written theirs.

I am assuming the counterargument is that it's all-or-nothing, but then why do .ts files that rely on .d.ts files typecheck fine when my .d.ts files are not typechecked? Can't that behavior be applied to definitions in node_modules?

Examples

Not sure how to show an example here. I would like to be able to run tsc --noEmit on my codebase and get errors for my own definitions files without having a bunch of noise from unfixable errors in node_modules/@types etc.

Checklist

My suggestion meets these guidelines:

This wouldn't be a breaking change in existing TypeScript/JavaScript code
If implemented as some additional flag?
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, etc.)
This feature would agree with the rest of TypeScript's Design Goals.
I think so?

It sounds like you're asking for the opposite - a mode for skipLibCheck that says only skip checking of .d.ts files from node_modules?

You're right, that wasn't the right phrasing (I was thinking of skipLibCheck: false—excluded from enabled libCheck).

FWIW I think this ongoing issue is my biggest use case for this flag: Styled-Components automatically includes React-Native types, which duplicate Node types, so if you use Styled-Components and Node, you must skipLibCheck because of a long-standing problem that you have no power to fix

Another use-case for this feature comes from nexus.

Nexus has a novel "typegen" feature wherein based on user code a TS types file is generated and via interface-merging is able to imbue static guarantees on otherwise dynamic app code.

We are currently working on making the default disk location for this typegen be node_modules/@types/whatever/index.d.ts. This allows nexus to provide the typegen DX without any config demands upon the user.

Now, the motivation, for us, for this TS issue, is that nexus typegen would become weaker in the face of skipLibCheck. Advanced users can configure typegen output, but their getting it wrong while skipLibCheck: true would make it silently fail. This TS feature would help maintain our users' confidence in nexus typegen even in situations where they need to skipLibCheck for just one or two libs in their project.

Hope that makes sense :)

I completely agree with the author.

I am not sure if it would make sense or whether this has any negative effect, but the only way I could make sure my declaration files didn't have any errors, was to rename all .d.ts to .ts, while keeping skipLibCheck=true.

I faced many situations where I did have errors on my .d.ts files to only figure it out once those were then checked by tsc after being renamed.

I might be missing something though.

My use case for this is also related to the styled-components and @types/react-native issue. I'm getting 40 errors.

It does not harm my code, so I would like to ignore all those errors by setting --skipLibChecks: true, while still checking and getting errors for my own .d.ts files inside my src folder.

Any updates on this?

We discussed this today and decided that its fate is linked to that of #39231. Currently, we have a fairly coherent posture that .d.ts files are either outputs or they describe the shape of colocated JS (as in libraries), but they’re not inputs to be hand-authored. There are reasons to reconsider that stance, but we would do so altogether, and such a change in perspective would likely address this issue and #39231, but it’s not something we’re actively exploring right now.

I'd propose a new setting

`"skipLibCheck": "external"

which says that any .d.ts file in your files or include pattern is checked, but any .d.ts file that gets into your program via other means is not (e.g. node_modules imports, output .d.ts files from upstream project references)

Thoughts?

We discussed this today and decided that its fate is linked to that of #39231. Currently, we have a fairly coherent posture that .d.ts files are either outputs or they describe the shape of colocated JS (as in libraries), but they’re not inputs to be hand-authored. There are reasons to reconsider that stance, but we would do so altogether, and such a change in perspective would likely address this issue and #39231, but it’s not something we’re actively exploring right now.

What about this kind of types collection? https://github.com/sindresorhus/type-fest

fix: revert `skipLibCheck` to true

Those files are not exempt from the behavior I described. If you import from type-fest with the compiler option --importsNotUsedAsValues preserve, the output will crash despite not hearing an error from us. When type-fest exposes module .d.ts files that export types, it implies that there are corresponding .js files that export nothing, which is very different from there not being .js files. To correctly reason about a library like type-fest, we would need a completely new concept of a type-only module, which is known to have no runtime counterpart. Alternatively, collections of utility types could choose to declare a global namespace rather than modules, so users would just use tf.EmptyObject instead of importing EmptyObject, for example. But I understand why that feels less desirable. Fortunately, the majority of users have no reason to set --importsNotUsedAsValues preserve, and many folks are writing import type for these imports anyway, so in practice, I don’t think anyone is getting hit by this. But hopefully it explains that yes, even type-fest technically implies the existence of a set of empty .js modules.

Coming here from #43140.

I am trying to enable project references in Babel to speed up incremental type checking, and this is being a partial blocker.

We cannot use skipLibCheck, because we have multiple manually-written .d.ts files that need to be checked. When migrating to project references, type checking gets more than 3x slower:

"monolithic project" with skipLibCheck: false takes ~3 minutes
project references with skipLibCheck: false takes ~10 minutes
project references with skipLibCheck: true takes ~3 minutes

As a workaround, we are probably going to use skipLibCheck: true in most projects expect for the ones that contain manually-written .d.ts files, but:

it still incurs in a ~20 seconds performance penalty for each project that has skipLibCheck: false
it's easy to accidentally forget to set skipLibCheck: false in a project when adding a .d.ts file.

For this use case, skipLibCheck should accept a pattern so that I can exclude .d.ts files generated by tsc (while still type-checking manually-written .d.ts and .d.ts from my dependencies):

{
  "compilerOptions": {
    "skipLibCheck": [
      "./packages/*/lib/**/*.d.ts",
      "./codemods/*/lib/**/*.d.ts",
      "./eslint/*/lib/**/*.d.ts",
    ]
  },
}

I'd be happy to open a PR for it.

That difference seems surprising. Do you have an active PR/branch with the above I could test? I was thinking it might be babel/babel#16416 but that doesn't actually seem to be it.

test/static-code: tweak Typescript config again

I fully agree with this. Another (admitted niche) user case: I'm using https://github.com/Tencent/puerts for my game It's a Javascript/Typescript runtime for Unity. To access C# runtime from Typescript, it generated *.d.ts files from C# classes. However, in most case you'd like to draw a clear line between C# codebase and Typescript codebase, and therefore only want to generate *.d.ts for a few classes that "glue" between C# and TS.

Obviously, it would cause some unresolvable symbols in those generated *.d.ts, and it's totally fine. But I'd still like to check other *.d.ts files that are NOT generated from C#.

Ryan Cavanaugh (@RyanCavanaugh)

Hello Ryan Cavanaugh (@RyanCavanaugh) Andrew Branch (@andrewbranch) , is there any intention to review these types of cases? There are a lot of issues referencing these behaviours but nothing concrete is achieved. There are a lot of use cases for having this property skipping folder patterns, something like skipLibCheck: ["node_modules/", "./src/undesired_handwritten.d.ts"].
Even working with project references is a nightmare when it comes to monorepos (widely used today). I feel that no one has paid attention to specific behaviors that typescript has (or ignores them) otherwise the community would have stopped using typescript a long time ago.

There are some big gaps in the explanations of how tsconfig files actually work. I absolutely believe that more than 90% of the community believes that an exclude: ["node_modules/"] is saying that typescript will not check for files in that folder so they are ignored even though the documentation explains it. Configuration properties names must convey their intent, which tsconfig files do not.

There are problems when dealing with typescript projects from different environments (or intentions), such as whether I want to verify source, tests, storybook, e2e, build or node files. I'm almost sure people think that adding a tsconfig.node.json
will actually check the types of your included files (unless you specify that file in the tsc command). We don't have a clear way to check everything at once avoiding type collisions, configurations, without using the annoying, unpredictable, slow and almost undocumented project references. On many occasions I have seen proposals and suggestions from the community, such as an override per environment in a single tsconfig.json file, but I feel that everything the community suggests is still being ignored, even if it solves real problems .

We must do something

robert-melonn

My 2 cents

I probably riding the bandwagon here, but I want to add my thoughts as someone who runs into this issue in every single TS project and has yet to find a suitable solution. I've always enabled skipLibCheck, but the fact that it doesn't check types in my local index.d.ts files is something I know but most don't. I remember when I first found that out by mistake.

Type checking someone else's files

It makes no sense to me that I'd wanna check someone else's types when it's their job to check their own types before releasing a version of their library. I have to have trust that the library I'm importing is both tested and functional; I can't make an assumption that they did everything wrong because fixing it isn't my job, and not something I can easily control.

I'm sure there's a great argument for why you need to check someone else's types in your library similar to the argument for why it's important to re-bundle someone else's production library code because they might've used a different browserslist config.

As unintuitive as it may seem, skipLibCheck: true should probably be the default. Like robert-melonn suggested, I assumed that excluding a directory also excludes it from type checking. Wasting hours on an issue caused by an unintuitive config file setting isn't a great user experience. TypeScript will have more new users than old users over time, and they're all gonna run into this same issue as I did. It's a 100% given. I don't know anyone who hasn't run into this issue.

How I got here

The entire reason I found this thread is because I'm trying to figure out a way to have local index.d.ts files for when I need to create types for a 3rd party library, but that file isn't typechecked, and any attempt at doing types.ts doesn't work the same when using "type": "module". If this is supposed to work, I'd argue the documentation is lacking, and that all stems from the fact that it's unintuitive.

Kevin Ghadyani (@KevinGhadyani-Okta)

Kevin Ghadyani (@KevinGhadyani-Okta) Use declare global { ... } instead of the .d.ts extension. Same thing but not affected by skipLibCheck.

Georgii Dolzhykov (@thorn0)

Georgii Dolzhykov (@thorn0) declare global is just for modules that use window object. It shouldnt be used arbitrarily

Ryan Cavanaugh (@RyanCavanaugh)

Ryan Cavanaugh (@RyanCavanaugh):

I'd propose a new setting

`"skipLibCheck": "external"

robert-melonn:

There are a lot of use cases for having this property skipping folder patterns, something like skipLibCheck: ["node_modules/", "./src/undesired_handwritten.d.ts"].

I'd like to say I prefer something similar to robert-melonn 's idea. Maybe this property could be extended to take glob patterns. I would probably want to use something like this: skipLibCheck: ["!./src/**"] to say, "Exclude every lib check except those in my src dir.

Here's my use case: DevExpress/testcafe-hammerhead#3036

To summarize, testcafe-hammerhead has a dependency whose types conflict with typescript's own (node-lru-cache). But I don't want to skipLibCheck: true because I had to write some type declarations by hand: I'm using old versions of libraries that predate DefinitelyTyped types. Current versions of the library have @types, but not the versions I'm using.

In the meanwhile, I created the following script to report all issues (skipLibCheck: false) but excluding the ones coming from node_modules. It is meant to be used in projects with references (incremental builds) (equivalent to tsc --build).

I use TypeScript - 5.8.3

const {readFile} = require('node:fs/promises');
const {dirname, join, relative} = require('node:path');
const ignore = require('ignore');
const {
    formatDiagnostic,
    sys,
    createSolutionBuilderHost,
    getParsedCommandLineOfConfigFile,
    DiagnosticCategory,
    formatDiagnosticsWithColorAndContext,
    createSolutionBuilder
} = require('typescript');

// https://github.com/microsoft/TypeScript/issues/30511
// https://github.com/microsoft/TypeScript/issues/62035

const script = {
    name: 'build-types',
    fn: async (input = {}) => {
        const basePath = dirname(input.configFile);

        const ignoreFilePath = join(basePath, '.buildtypesignore');

        const ignoreFileContent = await readFile(ignoreFilePath)
            .then((content) => content.toString())
            .catch((err) => {
                if (err.code === 'ENOENT') {
                    return null;
                } else {
                    throw err;
                }
            });

        const ig = ignore();

        if (ignoreFileContent) {
            ig.add(ignoreFileContent);
        }

        // FUNCTIONS TO FORMAT DIAGNOSTICS (REUSED FOR CONSISTENCY)

        const format = (diagnostic) => {
            return formatDiagnostic(diagnostic, {
                getCanonicalFileName: (fileName) => fileName,
                getCurrentDirectory: sys.getCurrentDirectory,
                getNewLine: () => sys.newLine
            });
        };

        const formatWithColorAndContext = (diagnostic) => {
            return formatDiagnosticsWithColorAndContext([diagnostic], {
                getCanonicalFileName: (fileName) => fileName,
                getCurrentDirectory: sys.getCurrentDirectory,
                getNewLine: () => sys.newLine
            });
        };

        const context = {
            lastProjectName: null,
            externalDiagnostics: [],
            internalDiagnostics: [],
            configsMap: new Map(),
            diagnosticsMetaMap: new WeakMap(),
            isLibCheckOverride: false
        };

        // CREATE THE DEFAULT SOLUTION BUILDER HOST FIRST
        const defaultHost = createSolutionBuilderHost(sys);

        // NOW, CREATE A CUSTOM HOST BY EXTENDING THE DEFAULT ONE
        const customHost = {
            ...defaultHost,

            createProgram: (...args) => {
                const program = defaultHost.createProgram(...args);

                const [, options] = args;

                context.lastProjectName = options.configFilePath || null;

                return program;
            },

            // OVERRIDE getParsedCommandLine TO MODIFY OPTIONS FOR EACH PROJECT. THIS FUNCTION IS CALLED BY THE SOLUTION BUILDER FOR EACH TSCONFIG FILE IT PROCESSES
            getParsedCommandLine: (fileName) => {
                const parsed = getParsedCommandLineOfConfigFile(
                    fileName,
                    {},
                    {
                        ...sys,
                        onUnRecoverableConfigFileDiagnostic: (diagnostic) => {
                            console.error(format(diagnostic));
                        }
                    }
                );

                if (typeof parsed !== 'object' || parsed === null) {
                    return parsed;
                }

                // ADJUST CONFIG FOR LIB CHECKING
                if (typeof input.libCheck === 'boolean') {
                    if (input.libCheck) {
                        if (parsed.options.skipLibCheck) {
                            context.isLibCheckOverride = true;
                        }

                        parsed.options.noEmitOnError = false;
                        parsed.options.skipLibCheck = false;
                    } else {
                        parsed.options.skipLibCheck = true;
                    }
                }

                context.configsMap.set(parsed.options.configFilePath, {
                    rootDir: parsed.options.rootDir,
                    declarationDir: parsed.options.declarationDir
                });

                return parsed;
            },

            // OVERRIDE reportDiagnostic TO ADD FILTERING LOGIC
            reportDiagnostic: (diagnostic) => {
                if (!diagnostic.file) {
                    return;
                }

                const filePath = diagnostic.file.fileName;

                if (ig.ignores(relative(basePath, filePath))) {
                    return;
                }

                // FILTER DIAGNOSTICS: SEPARATE EXTERNAL AND INTERNAL ONES
                if (
                    filePath.includes('node_modules') ||
                    filePath.includes('.yarn')
                ) {
                    context.externalDiagnostics.push(diagnostic);

                    context.diagnosticsMetaMap.set(diagnostic, {
                        filePath,
                        project: context.lastProjectName,
                        scope: 'external'
                    });
                } else {
                    context.internalDiagnostics.push(diagnostic);

                    context.diagnosticsMetaMap.set(diagnostic, {
                        filePath,
                        project: context.lastProjectName,
                        scope: 'internal'
                    });
                }
            },

            // OVERRIDE reportSolutionBuilderStatus
            reportSolutionBuilderStatus: (diagnostic) => {
                // THESE ARE USUALLY BUILD STATUS MESSAGES, NOT CODE ERRORS.
                console.log(format(diagnostic));
            }
        };

        // CREATE THE SOLUTION BUILDER USING THE CUSTOM HOST
        const builder = createSolutionBuilder(
            customHost,
            // PATH TO THE ROOT tsconfig.json (THE ONE WITH ALL PROJECTS 'references')
            [input.configFile],
            {
                verbose: input.verbose,
                stopBuildOnErrors: input.bail
            }
        );

        // EXECUTE THE BUILD
        console.log();
        console.log('STARTING SOLUTION BUILD...');
        console.log();

        builder.build();

        console.log('SOLUTION BUILD FINISHED.');
        console.log();

        let output = [];

        switch (input.showDiagnostics) {
            case 'all':
                output = [
                    ...context.internalDiagnostics,
                    ...context.externalDiagnostics
                ];
                break;

            case 'internal':
                output = [...context.internalDiagnostics];
                break;

            case 'external':
                output = [...context.externalDiagnostics];
                break;

            case 'none':
            default:
                break;
        }

        // AFTER THE BUILD, FORMAT AND PRINT THE COLLECTED DIAGNOSTICS ACCORDING TO OPTIONS
        if (output.length) {
            console.log('DIAGNOSTICS:\n');

            const showCategory = (diagnostic) => {
                let label;

                switch (diagnostic.category) {
                    case DiagnosticCategory.Warning:
                        label = 'WARNING';
                        break;
                    case DiagnosticCategory.Error:
                        label = 'ERROR';
                        break;
                    case DiagnosticCategory.Suggestion:
                        label = 'INFO';
                        break;
                    case DiagnosticCategory.Message:
                        label = 'MESSAGE';
                        break;
                    default:
                        label = 'UNKNOWN';
                        break;
                }

                console.log(`CATEGORY: ${label}`);
            };

            const showLocation = (meta) => {
                const config = context.configsMap.get(meta.project);

                if (config && meta.filePath) {
                    if (meta.scope === 'internal') {
                        if (
                            config.declarationDir &&
                            meta.filePath.startsWith(config.declarationDir)
                        ) {
                            console.log('LOCATION: DECLARATION');
                        } else if (
                            config.rootDir &&
                            meta.filePath.startsWith(config.rootDir)
                        ) {
                            console.log('LOCATION: SOURCE');
                        } else {
                            console.log('LOCATION: OUTSIDE OF SOURCE');
                        }
                    } else {
                        console.log('LOCATION: DEPENDENCY');
                    }
                } else {
                    console.log('LOCATION: UNKNOWN');
                }
            };

            switch (input.groupDiagnosticsBy) {
                case 'project': {
                    const groups = {};

                    output.forEach((diagnostic) => {
                        const meta = context.diagnosticsMetaMap.get(diagnostic);

                        if (groups[meta.project]) {
                            groups[meta.project].push({diagnostic, meta});
                        } else {
                            groups[meta.project] = [{diagnostic, meta}];
                        }
                    });

                    Object.entries(groups).forEach(
                        ([project, entries], index, array) => {
                            console.log(`PROJECT: ${project}\n`);

                            entries.forEach(({diagnostic, meta}) => {
                                showCategory(diagnostic);
                                showLocation(meta);

                                const formatted =
                                    formatWithColorAndContext(diagnostic);

                                console.log(formatted);
                            });

                            if (index < array.length - 1) {
                                console.log('\n---\n');
                            }
                        }
                    );

                    break;
                }

                case 'none':
                default:
                    output.forEach((diagnostic, index) => {
                        const meta = context.diagnosticsMetaMap.get(diagnostic);

                        console.log(`PROJECT: ${meta.project || 'Unknown'}`);

                        showCategory(diagnostic);
                        showLocation(meta);

                        const formatted = formatWithColorAndContext(diagnostic);

                        console.log(formatted);

                        if (index < output.length - 1) {
                            console.log('\n---\n');
                        }
                    });
                    break;
            }
        }

        console.log();
        console.log(`DIAGNOSTICS FOUND: ${output.length}`);
        console.log();

        if (output.length) {
            if (context.isLibCheckOverride) {
                console.log(
                    'YOU MIGHT NEED TO TEMPORARILY DISABLE "skipLibCheck" IN YOUR TYPESCRIPT CONFIG TO ADDRESS VIA YOUR IDE'
                );
            }

            if (input.ci) {
                throw new Error('BUILD CONTAINS ERRORS. SEE LOGS ABOVE.');
            }
        }
    }
};

module.exports = {script};

Inputs:

const inputs = {
    configFile: {
        type: 'string',
        describe: 'Path to config file'
    },
    verbose: {
        type: 'boolean',
        describe: 'Increase verbosity of the output'
    },
    groupDiagnosticsBy: {
        type: 'string',
        describe: 'Specifies how diagnostics should be grouped',
        choices: ['project', 'none']
    },
    showDiagnostics: {
        type: 'string',
        describe: 'Specifies which diagnostics should be showed',
        choices: ['all', 'internal', 'external', 'none']
    },
    libCheck: {
        type: 'boolean',
        describe: 'Whether to check libraries'
    },
    ci: {
        type: 'boolean',
        describe: 'Throw if diagnostics are found'
    },
    bail: {
        type: 'boolean',
        describe: 'Exit on first diagnostic'
    }
};

I call it via a CLI created with yargs.

UPDATE: Script edited to include more features.

NOTE: Beware of #62035

Any update on this?

We discussed this today and decided that its fate is linked to that of #39231. Currently, we have a fairly coherent posture that .d.ts files are either outputs or they describe the shape of colocated JS (as in libraries), but they’re not inputs to be hand-authored. There are reasons to reconsider that stance, but we would do so altogether, and such a change in perspective would likely address this issue and #39231, but it’s not something we’re actively exploring right now.

^ #30511 (comment)

This ignores the reality of how TS is being used and degrades DX. Please "actively explore" changing this.

I'd propose a new setting

`"skipLibCheck": "external"

which says that any .d.ts file in your files or include pattern is checked, but any .d.ts file that gets into your program via other means is not (e.g. node_modules imports, output .d.ts files from upstream project references)

Thoughts?

^ #30511 (comment)

Yes, please. 🙏

I understand the design intent, but this does not match real-world TypeScript usage.
.d.ts files are very often hand-authored. That is the entire purpose of DefinitelyTyped, and it is explicitly documented in the official handbook (1, 2). Treating them as “outputs only” ignores a common and documented workflow and directly leads to the skipLibCheck DX issues raised in this thread.

Navigation Menu

Repository navigation

Feature Request: allow exclusion of node_modules when skipLibCheck is false #30511

Search Terms

Suggestion

Use Cases

Examples

Checklist

4 remaining items

My 2 cents

Type checking someone else's files

How I got here

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Feature Request: allow exclusion of node_modules when skipLibCheck is false #30511

Description

Search Terms

Suggestion

Use Cases

Examples

Checklist

Activity

RyanCavanaugh commented on Mar 26, 2019

bensaufley commented on Mar 26, 2019

bensaufley commented on Jul 5, 2019

jasonkuhrt commented on Sep 30, 2019

zanona commented on Nov 27, 2020

cbdeveloper commented on Jan 6, 2021

andrewbranch commented on Aug 30, 2021

RyanCavanaugh commented on Apr 19, 2022

skarab42 commented on Sep 21, 2022

andrewbranch commented on Sep 21, 2022

4 remaining items

nicolo-ribaudo commented on Apr 14, 2024

jakebailey commented on Apr 14, 2024

kodra-dev commented on Sep 9, 2024

robert-melonn commented on Oct 29, 2024

KevinGhadyani-Okta commented on Nov 7, 2024

My 2 cents

Type checking someone else's files

How I got here

thorn0 commented on Nov 7, 2024

robert-melonn commented on Nov 8, 2024

DanKaplanSES commented on Mar 1, 2025

ernestostifano commented on Jul 10, 2025

alexsch01 commented on Aug 8, 2025

DayKev commented on Jan 15, 2026

skarab42 commented on Jan 15, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions