stylelint-codeframe-formatter

1.2.0 verified Sat Apr 25 auth: no javascript

A custom formatter for Stylelint that displays lint results with a babel-code-frame, showing the exact source code where errors/warnings occur, along with filenames and line:column references for clickable navigation. Current stable version 1.2.0 (released 2023-06). Maintained as a minor/major update cycle; last release fixes CSS syntax error display. Key differentiator: provides inline code context unlike Stylelint's built-in formatters, helping developers quickly locate issues. Requires Stylelint as a peer dependency.

Common errors

error Error: Cannot find module 'stylelint-codeframe-formatter' ↓

cause Package not installed or not in node_modules.

fix

Run: npm install stylelint-codeframe-formatter --save-dev

error The constructor must be a function that returns an object or the formatter expects to be a function ↓

cause Using namespace import (import * as) instead of default import in ESM.

fix

Use: import formatter from 'stylelint-codeframe-formatter'

error stylelint-codeframe-formatter: Failed to display codeframe: Cannot read property 'type' of null ↓

cause Issue with empty result or malformed node (fixed in v1.0.6).

fix

Upgrade to >=1.0.6

Warnings

gotcha The formatter may show 'undefined' for rule name when the message duplicates the rule name (fixed in v1.2.0). ↓

fix Upgrade to >=1.2.0

breaking v1.0.6 fixed an issue with empty stylelint results; earlier versions could crash. ↓

fix Upgrade to >=1.0.6

deprecated The package uses babel-code-frame; babel-code-frame is deprecated in favor of @babel/code-frame (upgraded in v1.0.5). ↓

fix Upgrade to >=1.0.5

gotcha When using with stylelint-webpack-plugin, ensure the formatter is required correctly: formatter: require('stylelint-codeframe-formatter') (not the path). ↓

fix Use require('stylelint-codeframe-formatter') in the plugin options

Install

npm install stylelint-codeframe-formatter

yarn add stylelint-codeframe-formatter

pnpm add stylelint-codeframe-formatter

Imports

default
wrong
```
const { default: formatter } = require('stylelint-codeframe-formatter')
```
correct
```
import formatter from 'stylelint-codeframe-formatter'
```
ESM default export; CommonJS users can use require('stylelint-codeframe-formatter') directly, but this is the ESM way.

formatter

wrong

const formatter = require('stylelint-codeframe-formatter').default

correct

const formatter = require('stylelint-codeframe-formatter')

CommonJS require returns the default export directly; do not access .default in CJS.

formatter as default import in TypeScript
wrong
```
import * as formatter from 'stylelint-codeframe-formatter'
```
correct
```
import formatter from 'stylelint-codeframe-formatter'
```
TypeScript uses default import; namespace import may cause runtime issues.

Quickstart

Demonstrates installing the formatter, using it via Stylelint CLI, and integrating programmatically with lint results.

// Install: npm install stylelint stylelint-codeframe-formatter --save-dev
// Use with Stylelint CLI:
// stylelint --custom-formatter node_modules/stylelint-codeframe-formatter/index.js "src/**/*.css"

// Or programmatically (ESM):
import formatter from 'stylelint-codeframe-formatter';
import stylelint from 'stylelint';

const result = await stylelint.lint({
  files: 'src/**/*.css',
  formatter: formatter,
});
console.log(result.output);