or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

built-in-rules.mdconfiguration.mdindex.mdplugin-development.mdprogrammatic-api.md
tile.json

tessl/npm-stylelint

A mighty CSS linter that helps you avoid errors and enforce conventions.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/stylelint@16.23.x

To install, run

npx @tessl/cli install tessl/npm-stylelint@16.23.0

index.mddocs/

Stylelint

Stylelint is a comprehensive CSS linting tool that helps developers avoid errors and enforce consistent coding conventions across CSS, SCSS, Sass, Less, and SugarSS stylesheets. It features over 100 built-in rules for modern CSS syntax validation, supports custom plugins for extending functionality, provides automatic fixing capabilities where possible, and offers shareable configuration presets.

Package Information

  • Package Name: stylelint
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install stylelint

Core Imports

import stylelint from "stylelint";

For CommonJS:

const stylelint = require("stylelint");

Named imports:

import { lint, rules, formatters, createPlugin, resolveConfig, utils } from "stylelint";

Note: Named imports are not directly supported - use default import and destructure:

import stylelint from "stylelint";
const { lint, rules, formatters, createPlugin, resolveConfig, utils } = stylelint;

Basic Usage

import stylelint from "stylelint";

// Lint CSS code
const result = await stylelint.lint({
  code: `
    .example {
      color: #ffffff;
      font-weight: bold;
    }
  `,
  config: {
    rules: {
      "color-hex-length": "short",
      "font-weight-notation": "numeric"
    }
  }
});

console.log(result.results[0].warnings);

Architecture

Stylelint is built around several key components:

  • Linting Engine: Core linting functionality that processes CSS and applies rules
  • Rule System: 139+ built-in rules covering all aspects of CSS validation and conventions
  • Plugin System: Extensible architecture for custom rules and functionality
  • Configuration System: Flexible configuration with extends, overrides, and shareable configs
  • Formatters: Various output formats for integration with different tools and workflows
  • PostCSS Integration: Built on PostCSS for robust CSS parsing and manipulation
  • CLI Interface: Command-line tool for file system integration and automation

Capabilities

Programmatic Linting

Core linting functionality for processing CSS code and files programmatically. The main API for integrating Stylelint into applications and build processes.

function lint(options: LinterOptions): Promise<LinterResult>;

interface LinterOptions {
  files?: string | string[];
  code?: string;
  config?: Config;
  configFile?: string;
  fix?: boolean;
  formatter?: FormatterType | Formatter;
  cwd?: string;
}

interface LinterResult {
  results: LintResult[];
  errored: boolean;
  report: string;
  code?: string;
  cwd: string;
}

Programmatic API

Built-in Rules

Complete collection of 139+ built-in rules for CSS validation and convention enforcement. Rules are categorized by CSS features and provide comprehensive coverage of modern CSS.

const rules: { readonly [name in keyof CoreRules]: Promise<CoreRules[name]> };

// Example rule types
type ColorHexLengthRule = Rule<'short' | 'long', {}, AutofixMessage>;
type PropertyNoUnknownRule = Rule<true, {
  ignoreProperties: string[];
  checkPrefixed: boolean;
}, RejectedMessage<[property: string]>>;

Built-in Rules

Configuration System

Comprehensive configuration system supporting extends, plugins, rule settings, and file-specific overrides. Enables both simple and complex linting setups.

interface Config {
  extends?: string | string[];
  plugins?: (string | Plugin)[];
  rules?: { [ruleName: string]: ConfigRuleSettings<any, Object> };
  ignoreFiles?: string | string[];
  overrides?: ConfigOverride[];
  customSyntax?: CustomSyntax;
}

function resolveConfig(
  filePath: string,
  options?: Pick<LinterOptions, 'cwd' | 'config' | 'configBasedir' | 'configFile'>
): Promise<Config | undefined>;

Configuration

Plugin Development

Plugin system for creating custom rules and extending Stylelint functionality. Provides utilities for rule creation, validation, and integration.

function createPlugin(ruleName: string, rule: Rule): Plugin;

interface Plugin {
  ruleName: string;
  rule: Rule;
}

interface Rule<P = any, S = any, M = RuleMessages> {
  (primaryOption: P, secondaryOptions: S, context: RuleContext): 
    (root: PostCSS.Root, result: PostcssResult) => Promise<void> | void;
  ruleName: string;
  messages: M;
  meta?: RuleMeta;
}

Plugin Development

Output Formatting

Multiple output formatters for different integration needs, from human-readable reports to machine-parsable formats.

interface Formatters {
  readonly compact: Promise<Formatter>;
  readonly github: Promise<Formatter>;
  readonly json: Promise<Formatter>;
  readonly string: Promise<Formatter>;
  readonly tap: Promise<Formatter>;
  readonly unix: Promise<Formatter>;
  readonly verbose: Promise<Formatter>;
}

type Formatter = (results: LintResult[], returnValue: LinterResult) => string;

PostCSS Integration

PostCSS plugin interface for seamless integration into PostCSS processing pipelines and build tools.

// stylelint as PostCSS plugin - the default export is a PostCSS plugin
const postcssPlugin: PostCSS.PluginCreator<PostcssPluginOptions>;

type PostcssPluginOptions = Omit<LinterOptions, 'customSyntax'> | Config;

Utility Functions

Developer utilities for rule creation, validation, and CSS processing. Essential tools for plugin authors and advanced usage scenarios.

interface Utils {
  report: (problem: Problem) => void;
  ruleMessages: <T extends RuleMessages>(ruleName: string, messages: T) => T;
  validateOptions: (result: PostcssResult, ruleName: string, ...options: RuleOptions[]) => boolean;
  checkAgainstRule: <T, O extends Object>(options: CheckAgainstRuleOptions<T, O>, callback: (warning: PostCSS.Warning) => void) => Promise<void>;
}

Reference Utilities

Complete collection of CSS reference data used by stylelint rules for property analysis, validation, and categorization.

interface Reference {
  /** Map of shorthand properties to their longhand sub-properties */
  longhandSubPropertiesOfShorthandProperties: LonghandSubPropertiesOfShorthandProperties;
  /** Properties that accept custom identifiers */
  acceptCustomIdentsProperties: ReadonlySet<string>;
  /** Map of shorthand properties to properties they reset to initial values */
  shorthandToResetToInitialProperty: ReadonlyMap<string, ReadonlySet<string>>;
  /** Properties that accept single color values */
  singleValueColorProperties: ReadonlySet<string>;
  /** Properties that accept multiple color values */
  multiValueColorProperties: ReadonlySet<string>;
  /** All color-related properties (single and multi-value) */
  colorProperties: ReadonlySet<string>;
  /** Longhand properties that accept time values */
  longhandTimeProperties: ReadonlySet<string>;
  /** Shorthand properties that accept time values */
  shorthandTimeProperties: ReadonlySet<string>;
  /** Properties valid in @page context */
  pageContextProperties: ReadonlySet<string>;
  /** Properties valid in margin context */
  marginContextProperties: ReadonlySet<string>;
}

type LonghandSubPropertiesOfShorthandProperties = ReadonlyMap<string, ReadonlySet<string>>;

Types

interface LintResult {
  source?: string;
  warnings: Warning[];
  errored?: boolean;
  ignored?: boolean;
  deprecations: { text: string; reference?: string }[];
  invalidOptionWarnings: { text: string }[];
  parseErrors: (PostCSS.Warning & { stylelintType: 'parseError' })[];
}

interface Warning {
  line: number;
  column: number;
  endLine?: number;
  endColumn?: number;
  rule: string;
  severity: 'warning' | 'error';
  text: string;
  url?: string;
  fix?: EditInfo;
}

interface EditInfo {
  range: [number, number];
  text: string;
}

type Severity = 'warning' | 'error';

type ConfigRuleSettings<T, O extends Object> = 
  | null 
  | undefined 
  | NonNullable<T> 
  | [NonNullable<T>] 
  | [NonNullable<T>, O];

interface Position {
  line: number;
  column: number;
}

interface Range {
  start: Position;
  end: Position;
}

interface CssSyntaxError {
  file?: string;
  input: {
    column: number;
    file?: string;
    line: number;
    source: string;
  };
  line: number;
  column: number;
  endLine?: number;
  endColumn?: number;
  message: string;
  name: string;
  reason: string;
  source: string;
}

interface DisableReportRange {
  rule: string;
  start: number;
  end?: number;
}

interface DisableReportEntry {
  source?: string;
  ranges: DisableReportRange[];
}

type DisableOptionsReport = DisableReportEntry[];

interface LanguageOptions {
  syntax?: {
    atRules?: Record<string, {
      comment?: string;
      prelude?: string;
      descriptors?: Record<string, string>;
    }>;
    cssWideKeywords?: string[];
    properties?: Record<string, string>;
    types?: Record<string, string>;
  };
}

interface InternalApi {
  _options: LinterOptions & { cwd: string };
  _extendExplorer: any; // cosmiconfig explorer
  _specifiedConfigCache: Map<Config, Map<string, any>>;
  _postcssResultCache: Map<string, any>; // PostCSS.Result
  _fileCache: FileCache;
}

interface FileCache {
  calcHashOfConfig: (config: Config) => void;
  hasFileChanged: (absoluteFilepath: string) => boolean;
  reconcile: () => void;
  destroy: () => void;
  removeEntry: (absoluteFilepath: string) => void;
}