Fix VSCode JSDoc: Check Entire Project in 2 Steps (2025)

Ever meticulously documented your JavaScript functions with JSDoc, only to find that VS Code doesn't seem to care unless the file is currently open? You're not alone. It's a common frustration that can undermine the very reason we use JSDoc: to catch errors and improve code quality across our entire project.

By default, VS Code treats your JavaScript files as a loose collection, only type-checking what's immediately in front of you. But what if you could unlock the full power of TypeScript's type-checker on your plain JavaScript project, everywhere, all the time? Good news: you can, and it only takes two simple steps. Let's fix this for good in your 2025 workflow.

The Frustrating Default: Why VS Code Only Checks Open Files

Before we jump into the fix, it helps to understand why VS Code behaves this way. The secret lies in how VS Code's JavaScript language service (which is powered by TypeScript under the hood) handles projects. Without any configuration, your collection of .js files is considered an "implicit project."

For performance reasons, an implicit project operates under a simple rule: only analyze the files you have open. This prevents VS Code from grinding to a halt trying to analyze every single file in your node_modules directory or other large folders. It's a sensible default, but it leaves us wanting more when we're trying to enforce type safety with JSDoc.

When you use JSDoc to define types, like @param {string} name, you're providing hints to the TypeScript engine. But in an implicit project, if you call that function incorrectly from a file that isn't open, VS Code remains silent. The error is there, lurking, but you won't see it until you happen to open both files at once. We can do better.

The 2-Step Fix for Project-Wide Checking

To solve this, we need to move from an "implicit" project to an "explicit" project. This tells VS Code exactly which files belong to your project and what rules to apply to them. The key to this is a single configuration file.

Step 1: Create a `jsconfig.json` File

The first step is to signal to VS Code that your directory is a dedicated JavaScript project. You do this by creating a new file named jsconfig.json in the root of your project.

Just creating this file is a huge step. It tells VS Code, "Hey, treat all the .js files in this folder and its subfolders as part of a single, unified project."

In your project's root directory, create the file jsconfig.json with the following content:

{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2022"
  },
  "exclude": ["node_modules"]
}

What does this do?

• compilerOptions: This is where we'll configure the behavior of the JavaScript language service.
• exclude: This is critically important. We're telling VS Code to ignore the node_modules folder. Without this, the type-checker would try to analyze all your dependencies, leading to slow performance and a flood of irrelevant errors.

At this point, you've already improved your development experience. Features like auto-imports and "Go to Definition" will now work across your entire project, not just open files. But we're not done yet—the type-checking is still off.

Step 2: Enable Project-Wide Checking with `checkJs`

Now for the magic. We need to tell the TypeScript engine to actually analyze our JavaScript files for JSDoc type errors. We do this by adding one line to our jsconfig.json.

Update your jsconfig.json to include "checkJs": true inside the compilerOptions:

{
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2022",
    "checkJs": true
  },
  "exclude": ["node_modules", "dist"]
}

And that's it! As soon as you save this file, VS Code's JavaScript engine will re-evaluate and start checking your entire project against your JSDoc annotations. You might need to reload the editor for the changes to take full effect (use the command palette: `Ctrl+Shift+P` and type "Developer: Reload Window").

Now, if you misuse a function or pass the wrong type to a JSDoc-annotated parameter anywhere in your project, VS Code will immediately flag it with a red squiggly line in the Problems panel—no matter which files are open.

Supercharge Your Setup: Understanding `jsconfig.json`

The two steps above are all you need to get started, but the jsconfig.json file is a powerful tool for fine-tuning your environment. It's essentially a sibling of TypeScript's tsconfig.json but with `"allowJs": true` implicitly enabled.

Implicit vs. Explicit Projects: A Quick Comparison

Here’s a clear breakdown of what you gain by creating a jsconfig.json file:

Essential `jsconfig.json` Options

Here are a few other `compilerOptions` you might find incredibly useful for a modern JavaScript project:

• "target": Specifies the ECMAScript version your code will be run on. Setting it to "ES2022" or "ESNext" allows you to use the latest JavaScript syntax without warnings.
• "module": Defines the module system. Use "NodeNext" for modern Node.js projects that use ES Modules, "CommonJS" for traditional Node.js, or "ESNext" for browser-based projects.
• "strict": A game-changer. Setting "strict": true enables a suite of stricter type-checking rules, such as ensuring variables are never implicitly any. It forces you to be more explicit and write more robust code.
• "include": The opposite of exclude. If you want to be very specific, you can tell VS Code to only include certain folders, like ["src/**/*"].

Advanced Example `jsconfig.json`

Here’s a more robust configuration for a typical web application project:

{
  "compilerOptions": {
    // Type Checking
    "checkJs": true,
    "strict": true,
    "noImplicitAny": true,

    // Module & Environment
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler", // Best for modern tools like Vite/Webpack

    // Path Aliases for Cleaner Imports
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist", "build"]
}

This configuration not only enables strict type checking but also sets up path aliases, so you can write import MyComponent from '@/components/MyComponent' instead of ugly relative paths.

Troubleshooting: "It's Still Not Working!"

If you've followed the steps and things aren't working, here are a few common culprits:

1. Invalid JSON: Your jsconfig.json file must be valid JSON. A common mistake is a trailing comma after the last entry in an object or array. Use VS Code's built-in JSON validation to check for errors.
2. File Location: The jsconfig.json file must be in the root directory of your project. If it's in a subfolder, VS Code won't detect it as the project's configuration file.
3. VS Code Needs a Refresh: Sometimes, the language server needs a kick to re-read the configuration. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and run the Developer: Reload Window command.
4. Conflicting Settings: Check your VS Code user or workspace settings (settings.json) for any conflicting JavaScript or TypeScript validation settings that might be overriding your jsconfig.json.

Conclusion: A More Robust JavaScript Workflow

By investing a few minutes to create and configure a jsconfig.json file, you elevate your plain JavaScript project to a new level of robustness. You're not just writing code; you're building a system where errors are caught early, code is more self-documenting, and your editor becomes a true partner in ensuring quality.

Moving from an implicit to an explicit project is the single biggest improvement you can make to your JSDoc workflow in VS Code. Stop hunting for errors file by file and let your editor do the heavy lifting across your entire codebase. Happy coding!