@codemirror/lint

@codemirror/lint is the official linting extension for the CodeMirror 6 code editor. It provides the machinery to attach one or more linters to an editor, collect the diagnostics they produce, and surface those problems to the user through underlines in the document, a color-coded gutter, hover tooltips, and a navigable lint panel.

Linters are plain functions that receive the editor view and return an array of diagnostics (synchronously or via a promise), each carrying a position range, severity, message, and optional quick-fix actions. The package debounces linting on document changes, renders the results, and ships a keymap and commands for opening the panel and jumping between problems, so integrators can wire up rich diagnostic feedback with only a few lines of configuration.

What You Get

• A linter() extension that runs your lint source (sync or async) with configurable debounce delay and refresh control.
• Document decorations, a color-coded lint gutter, and hover tooltips that render each diagnostic in place.
• A lint panel plus a keymap and commands (openLintPanel, nextDiagnostic, previousDiagnostic) for reviewing and navigating problems.
• A typed Diagnostic model with severities, sources, quick-fix Actions, and helpers like setDiagnostics, diagnosticCount, and forEachDiagnostic.

Common Use Cases

• Showing syntax or semantic errors from a language parser inline in a CodeMirror-based editor.
• Surfacing results from an external linter (ESLint, a JSON schema validator, a custom rule engine) as underlines and gutter markers.
• Offering one-click quick-fix actions attached to individual diagnostics.
• Building an in-editor problems panel that users can page through with the keyboard.

Under The Hood

Architecture

The entire package lives in a single ~1,015-line src/lint.ts module built on the CodeMirror 6 extension primitives. Diagnostics are held in a StateField updated through a setDiagnosticsEffect StateEffect, so lint results become part of editor state and are automatically mapped across document changes. A ViewPlugin (LintPlugin) debounces re-linting on updates and dispatches the effect when a lint source resolves; the state field derives a RangeSet of mark decorations, feeds hover tooltips via hoverTooltip, and drives an optional gutter (lintGutter) built from GutterMarkers. The lint panel is a showPanel construction that lists diagnostics and supports keyboard navigation through nextDiagnostic/previousDiagnostic commands.

Tech Stack

Written entirely in TypeScript (100% of the source) and published as dual ESM/CJS output with type declarations via the cm-buildhelper tool. Runtime dependencies are minimal and peer-aligned with the editor: @codemirror/state, @codemirror/view, and crelt (a tiny DOM element-creation helper). It targets CodeMirror 6 and carries no framework coupling beyond the editor core.

Code Quality

The public API is defined through documented TypeScript interfaces (Diagnostic, Action, LintSource) with /// doc comments that feed the generated reference docs. A test/test-lint.ts suite exercises the core behavior (diagnostic mapping, counting, panel navigation) with seven cases run through CodeMirror’s cm-runtests harness. The code is dense but consistently structured, favoring small exported functions and clear separation between state, view, and panel concerns.

API Design The surface is deliberately small and composable: a single linter() factory returns an extension you drop into your editor config, diagnostics are plain data objects, and everything else (gutter, keymap, panel) is opt-in. Naming is consistent with the wider CodeMirror ecosystem, and the reference documentation on codemirror.net covers every export. Getting a basic linter running takes only a lint function and the linter() call, while advanced needs (filters, custom rendering, quick-fix actions, auto-opening panels) are handled through well-typed configuration options.