Using ESLint in your development workflow is essential for maintaining code quality, especially on large-scale JavaScript or TypeScript codebases. It helps catch bugs, enforce coding standards, and generally streamline collaboration on projects. However, when you’re working with custom ESLint rules, things can sometimes go awry—and one common issue developers face is that their editor’s cursor or gutter indicators don’t show custom ESLint errors as expected. If you’re scratching your head wondering why your custom rules don’t show up, you’ve come to the right place!
TL;DR
If your text editor isn’t displaying your custom ESLint errors, it often comes down to misconfiguration in your ESLint setup or issues with editor integration. Make sure your rule is properly registered, compiled (if written in TypeScript), and that your ESLint config includes it. Also confirm that your IDE or text editor is set up to handle local rules through ESLint’s node resolution. Finally, restart your editor after changes—you’d be surprised how often that fixes things.
Why Your Custom ESLint Errors Aren’t Showing at the Cursor
So, you’ve written a custom ESLint rule, integrated it into your project, and expected to get instant feedback right in your code editor—but nothing shows up next to your code. No red squiggles. No gutter hints. Just silence. Let’s explore why this might happen.
1. The Linter Isn’t Picking Up Your Custom Rule
This is the most fundamental issue. ESLint must know about your custom rule before it can report any errors. Custom rules can be included in two ways:
- As part of a local plugin (a file in your repo like
eslint-rules/my-rule.js) - In a custom npm package (like
eslint-plugin-myplugin)
Ensure that your .eslintrc.js or equivalent ESLint config is importing and enabling your rule properly. If you’re using a local rule, make sure to attach it to a rule set and reference it with the correct path.
module.exports = {
rules: {
'no-secret-logs': require('./eslint-rules/no-secret-logs')
}
};In your config:
rules: {
'no-secret-logs': 'error'
}2. You Might Not Be Compiling TypeScript Rules
If your custom rule is written in TypeScript, remember that ESLint doesn’t understand TypeScript source natively. You need to compile the rule before ESLint can execute it. Use tsc or a bundler like esbuild to compile your rules to a common JS format, then point ESLint to the compiled output.
Check your tsconfig.json for the appropriate output directory, and ensure that your ESLint config isn’t accidentally pointing to the uncompiled TypeScript file.
Also, if you’re developing an in-repo ESLint plugin, make sure to set the correct Node resolution paths so ESLint can locate the compiled plugin code.
3. Your Editor May Not Be Using the Right ESLint
This is a subtle one: your editor might be using a global ESLint installation or not resolving your local custom rules properly. By default, editors like VSCode use the globally installed ESLint unless you explicitly tell them to use the local version defined in your node_modules.
To fix this in VSCode:
- Open
settings.json - Set
"eslint.nodePath"to"./node_modules" - Ensure you have ESLint extension by Dirk Baeumer installed
Also, ensure the ESLint extension is enabled and that there are no conflicting extensions overriding your Lint setup (like Prettier or other linters).
4. The Rule Isn’t Triggering—Code Doesn’t Match
Sometimes, everything is set up correctly, but your rule just isn’t firing. This happens when the code you’re writing doesn’t match the AST pattern your custom rule is looking to catch. Here’s what you can do:
- Add
console.logordebuggerstatements inside your rule’s visitor function - Use a tool like AST Explorer to test your rule logic
- Temporarily make your rule always error to check if it’s active
Once confirmed, go back to refining your matching logic. ESLint relies heavily on AST node patterns, and even a small mismatch will cause your rule to silently fail.
5. Rule Severity or Configuration May Be Wrong
ESLint won’t display warnings or errors if your rules are silently disabled. Your rule entry in the config might be set to "off" or have an invalid config shape. Basic checklist:
- Make sure rule name matches exactly
- Check its severity: Should be
"warn"or"error" - If it takes config options, make sure they are correctly formatted
rules: {
'no-secret-logs': ['error', { allow: ['console.info'] }]
}If any of these settings are malformed or mismatched, the rule won’t activate, and your editor understandably won’t show any linting feedback.
6. Plugin Version Mismatch and ESLint Compatibility
As ESLint evolves, its APIs and interfaces change too. Your custom rule or plugin might be using an outdated version of Rule APIs incompatible with your current ESLint version. Ensure both your custom plugin and rule files are written to support the ESLint version you’re using.
Verify versions using npm outdated or npm ls eslint and consider testing your rule against a minimal ESLint setup project. This helps isolate the error from other plugin interference.
Extra Tips to Debug Cursor Visibility Issues
Once you’re confident the rule is triggering correctly through CLI but not in the editor:
- Open editor developer tools (in VSCode:
Help > Toggle Developer Tools) - Navigate to the ESLint extension and look at logs
- Enable “ESLint: Trace Server Communication” to see detailed logs
This can help you pinpoint exactly why the rule isn’t showing feedback at the cursor—sometimes it’s as simple as needing to reload the project window.
Best Practices Moving Forward
To avoid facing this hassle repeatedly, consider the following best practices:
- Bundle your custom rules using a consistent build tool like Rollup or esbuild
- Write integration tests for your rules using ESLint’s
RuleTester - Use monorepo setups to link custom plugins alongside your codebase for easier path resolution
- Audit your ESLint configuration with
eslint --print-config file.js
Also, consider contributing frequently reusable rules to open-source plugins. This improves visibility and lets you validate your rule logic against diverse setups.
Conclusion
Getting your custom ESLint rules to show their messages at the cursor—in real-time—can be tricky, but it’s absolutely doable with the right approach. Whether the issue is your configuration, compilation, editor integration, or something as mundane as a cache hiccup, this guide covers the steps that will get you back on track.
Linting is one of the most powerful tools in a developer’s toolkit. By making sure your custom rules are properly recognized and displayed, you ensure your team benefits fully from the safety net ESLint offers.
