Tuning WebStorm's Node.js Debugger and TypeScript Checks for Real Projects

You open a TypeScript project in WebStorm, hit the debug button, and either nothing attaches or the editor stutters every time you save. The IDE ships with Node.js debugging, a TypeScript language service, and ESLint integration all switched on, but those defaults assume a generic project. When your start script lacks the right flag, your lint rules live in a file WebStorm hasn't noticed, or your monorepo has crossed a memory threshold, the tools stop helping and start getting in the way.

The useful move is not to turn features off, but to point them at your project's actual entry points and rule files.

Attaching the Node.js Debugger Without Guesswork

WebStorm's Run and Debug Node.js feature works by attaching to a Node process that has opened the Inspector protocol port. The --inspect flag tells Node to start that listener. Without it, there is nothing for WebStorm to attach to, and the IDE may report no inspectable processes or simply time out.

If you are on WebStorm 2024.x, assume the modern Inspector protocol is required. Older Node versions that only expose the legacy debug protocol are not reliably supported, so check your local runtime before blaming the IDE.

Edit your package.json in the project root (you need write access to the project directory) and add an explicit debug script:

{
  "scripts": {
    "start": "node server.js",
    "debug": "node --inspect=127.0.0.1:9229 server.js"
  }
}

Binding to 127.0.0.1:9229 keeps the debugger on localhost and avoids exposing the port to the network. Right-click the debug script in package.json and choose Debug. Expected check: the Debug tool window opens and breakpoints in server.js become active. Relevant risk: if another process already occupies port 9229, attachment fails; change the port or stop the conflicting process.

Tuning TypeScript Checking and ESLint Rules for Your Project

The TypeScript language service provides real-time error checking and refactoring suggestions in .ts files. It runs in the background and re-analyzes as you type. On large codebases, that checking intensity can significantly slow IDE responsiveness. You cannot simply ignore errors; you need to scope the analysis.

A practical decision is to exclude generated directories such as dist, build, and coverage from analysis, and to ensure tsconfig.json sits at the project root so WebStorm uses the same include and exclude rules as your compiler.

ESLint integration highlights linting errors on save, but only if it can find your configuration and the ESLint binary. Default settings may not match project requirements. If your team uses .eslintrc.js, WebStorm reads it automatically when the file is in the project root or a parent directory. If rules are not explicitly configured, the editor may show no warnings even when your CI pipeline fails.

A Worked Example: Wiring Debug and Lint in One Pass

Suppose you have a small Node.js service and you want both the debugger and a custom lint rule to work locally without freezing the editor.

1. Add the debug script shown above to package.json.
2. Create .eslintrc.js in the project root with a project-specific rule:

module.exports = {
  env: {
    node: true,
    es2022: true
  },
  extends: ['eslint:recommended'],
  rules: {
    'no-console': 'warn',
    'no-unused-vars': 'error'
  }
};

The extends array pulls in ESLint's recommended set; the rules block overrides or adds specifics. Setting no-unused-vars to error means the editor will flag unused variables as errors, not warnings.

1. In WebStorm, open the ESLint settings (typically under Languages & Frameworks | JavaScript | Code Quality Tools | ESLint) and confirm automatic configuration or point to the local node_modules/.bin/eslint.
2. Right-click the debug script and choose Debug.
3. Open a .ts file and introduce a type error, then open a .js file with an unused variable. Expected check: TypeScript underlines the type mismatch, and ESLint underlines the unused variable according to your .eslintrc.js rules.

Limitations and a Practical Verification Checklist

These integrations have real costs. Memory consumption increases substantially when working with monorepos containing many dependencies. Debugger attachment may fail with certain Node versions or when using older debugging protocols. TypeScript checking intensity can significantly slow IDE responsiveness on large codebases. And ESLint rules must be explicitly configured; default settings may not match project requirements.

Use this checklist to verify the setup rather than trusting defaults:

• Confirm your Node version supports the Inspector protocol and that your start script includes --inspect.
• Verify the inspector port is free and bound to localhost.
• Ensure tsconfig.json sits at the project root and excludes build output.
• Confirm .eslintrc.js (or .eslintrc.json) exists and WebStorm's ESLint integration is enabled.
• Open a file with a known violation to confirm highlighting fires before you rely on it.

WebStorm's value comes from the feedback loop, not the feature list. When the debugger attaches on the first try and the linter flags what your CI will flag, the IDE disappears. When it doesn't, you lose time to context switches. Spend ten minutes verifying these integration points, and the editor will match the project you actually have.