lint-to-the-future-stylelint

2.1.0 verified Fri May 01 auth: no javascript

A plugin for lint-to-the-future that integrates with stylelint to lint CSS files and track linting ignore comments. Current stable version 2.1.0 (released March 2025). Used to progressively enforce stylelint rules by marking files for future linting. Differentiates from direct stylelint usage by allowing incremental adoption via lint-to-the-future's ignore comment tracking. Works with stylelint v13, v14, and v15+. Requires Node 12+ (v2.x requires Node 18+).

Common errors

error Cannot find module 'lint-to-the-future-stylelint' ↓

cause Package not installed or wrong import path (CommonJS require in ESM-only v2).

fix

npm install lint-to-the-future-stylelint@2 and use import syntax.

error The requested module 'lint-to-the-future-stylelint' does not provide an export named 'default' ↓

cause Using require() or import * as when package is ESM-only.

fix

Use import lintToTheFutureStylelint from 'lint-to-the-future-stylelint' (default import).

error stylelint: Stylelint v15 requires Node >=18 ↓

cause Incompatible Node version for stylelint v15.

fix

Upgrade Node to >=18 or downgrade stylelint to v14.

error lint-to-the-future-stylelint: Unknown plugin option 'configFile' ↓

cause Using a config option that doesn't exist (likely confused with stylelint's configFile).

fix

Use the 'config' property as a stylelint config object, not 'configFile'.

Warnings

breaking v2.0.0 drops support for Node 14 and 16, and is ESM-only. ↓

fix Upgrade Node to >=18 and ensure project uses ESM (type: module or .mjs extension). Remove any require() calls for this package.

deprecated stylelint v13 and v14 are still supported as peer dependencies, but stylelint v15+ is recommended. ↓

fix Update to v2.1.0 which supports stylelint v15+. For stylelint v13/v14, stay on v1.x.

gotcha The plugin only processes files with /* stylelint-disable */ comments. Files without such comments are ignored. ↓

fix Ensure your CSS files contain the appropriate stylelint-disable comments for lint-to-the-future to track.

gotcha The plugin uses globby for file globbing since v2.1.0; behavior may differ from previous micromatch-based ignoring. ↓

fix Review your ignore patterns to ensure they work with globby syntax. Refer to globby documentation.

Install

npm install lint-to-the-future-stylelint

yarn add lint-to-the-future-stylelint

pnpm add lint-to-the-future-stylelint

Imports

lintToTheFutureStylelint

wrong

const lintToTheFutureStylelint = require('lint-to-the-future-stylelint')

correct

import lintToTheFutureStylelint from 'lint-to-the-future-stylelint'

Package is ESM-only since v2.0.0. Requires Node >=18.

LintToTheFutureStylelintPlugin

wrong

import { LintToTheFutureStylelint } from 'lint-to-the-future-stylelint'

correct

import { LintToTheFutureStylelintPlugin } from 'lint-to-the-future-stylelint'

Named export is available for TypeScript users. Correct symbol is LintToTheFutureStylelintPlugin.

default

wrong

import * as ltffStylelint from 'lint-to-the-future-stylelint'

correct

import ltffStylelint from 'lint-to-the-future-stylelint'

Default export is the plugin instance. Avoid namespace import for correct usage.

Quickstart

Shows how to create the plugin and use it with lint-to-the-future to track stylelint-disable comments.

import { LintToTheFutureStylelintPlugin } from 'lint-to-the-future-stylelint';

const plugin = new LintToTheFutureStylelintPlugin({
  // optional: specify stylelint config (default: stylelint's standard config)
  config: {
    extends: 'stylelint-config-standard'
  }
});

// Use with lint-to-the-future:
import lintToTheFuture from 'lint-to-the-future';
const lttf = new lintToTheFuture({
  plugins: [plugin]
});

// Then run lttf.process() to check files with stylelint-disable comments
await lttf.process({ files: ['src/**/*.css'] });