or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

tessl/npm-stylelint-config-recommended

Recommended shareable config for Stylelint that helps avoid CSS errors

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/stylelint-config-recommended@17.0.x

To install, run

npx @tessl/cli install tessl/npm-stylelint-config-recommended@17.0.0

Stylelint Config Recommended

A recommended shareable configuration for Stylelint that focuses on avoiding CSS errors. This package provides a comprehensive set of rules that help developers detect common CSS mistakes, unknown properties and selectors, and invalid syntax patterns.

Package Information

Package Name: stylelint-config-recommended
Package Type: npm
Language: JavaScript
Installation: npm install stylelint-config-recommended --save-dev

Core Imports

// Import the configuration object
const config = require('stylelint-config-recommended');

For ES modules:

import config from 'stylelint-config-recommended';

Basic Usage

Add the configuration to your Stylelint setup:

{
  "extends": "stylelint-config-recommended"
}

The configuration can also be extended with additional rules:

{
  "extends": "stylelint-config-recommended",
  "rules": {
    "block-no-empty": null,
    "unit-allowed-list": ["em", "rem", "s"]
  }
}

Architecture

Stylelint Config Recommended operates as a shareable configuration package within the Stylelint ecosystem. Understanding its architecture helps developers effectively integrate and extend the configuration:

Configuration System: Stylelint uses a modular configuration system where rules can be enabled, disabled, or configured with options. This package provides a curated set of rules focused specifically on error prevention.

Shareable Config Pattern: The package follows Stylelint's shareable config convention by exporting a configuration object that can be extended via the "extends" property in Stylelint configurations. This allows multiple projects to share the same rule base while customizing specific rules as needed.

Rule Engine Integration: When Stylelint processes CSS, it loads this configuration and applies each rule in the rules object to the CSS being analyzed. Rules are processed independently, with each rule's configuration determining its behavior (enabled/disabled, options, severity level).

Extension Hierarchy: Configurations can extend multiple shareable configs, with later configurations overriding earlier ones. This package is often used as a foundation, extended by more opinionated configs like stylelint-config-standard.

Peer Dependency Design: The package requires Stylelint as a peer dependency, ensuring compatibility with the user's specific Stylelint version while avoiding version conflicts in dependency trees.

Capabilities

Configuration Object

The main export provides a Stylelint configuration object containing error-prevention rules.

/**
 * Stylelint configuration object with recommended rules
 * @type {StylelintConfig}
 */
module.exports = {
  rules: {
    // Rule configurations (see Rules section for complete list)
  }
};

interface StylelintConfig {
  rules: Record<string, boolean | [boolean, any] | any>;
}

Rules Configuration

The configuration includes 41 rules focused on preventing CSS errors:

// Annotation and At-rule Validation
'annotation-no-unknown': true;
'at-rule-descriptor-no-unknown': true;
'at-rule-descriptor-value-no-unknown': true;
'at-rule-no-deprecated': true;
'at-rule-no-unknown': true;
'at-rule-prelude-no-invalid': [true, { ignoreAtRules: ['media'] }];

// Block and Comment Validation
'block-no-empty': true;
'comment-no-empty': true;

// Custom Property Validation
'custom-property-no-missing-var-function': true;

// Declaration Block Validation
'declaration-block-no-duplicate-custom-properties': true;
'declaration-block-no-duplicate-properties': [
  true,
  { ignore: ['consecutive-duplicates-with-different-syntaxes'] }
];
'declaration-block-no-shorthand-property-overrides': true;
'declaration-property-value-keyword-no-deprecated': true;
'declaration-property-value-no-unknown': true;

// Font Family Validation
'font-family-no-duplicate-names': true;
'font-family-no-missing-generic-family-keyword': true;

// Function Validation
'function-calc-no-unspaced-operator': true;

// Keyframe Validation
'keyframe-block-no-duplicate-selectors': true;
'keyframe-declaration-no-important': true;

// Media Feature and Query Validation
'media-feature-name-no-unknown': true;
'media-feature-name-value-no-unknown': true;
'media-query-no-invalid': true;
'media-type-no-deprecated': true;

// Grid and Nesting Validation
'named-grid-areas-no-invalid': true;
'nesting-selector-no-missing-scoping-root': true;

// General CSS Validation
'no-descending-specificity': true;
'no-duplicate-at-import-rules': true;
'no-duplicate-selectors': true;
'no-empty-source': true;
'no-invalid-double-slash-comments': true;
'no-invalid-position-at-import-rule': true;
'no-invalid-position-declaration': true;
'no-irregular-whitespace': true;

// Property Validation
'property-no-deprecated': true;
'property-no-unknown': true;

// Selector Validation  
'selector-anb-no-unmatchable': true;
'selector-pseudo-class-no-unknown': true;
'selector-pseudo-element-no-unknown': true;
'selector-type-no-unknown': [true, { ignore: ['custom-elements'] }];

// String and Syntax Validation
'string-no-newline': [true, { ignore: ['at-rule-preludes', 'declaration-values'] }];
'syntax-string-no-invalid': true;

Rule Categories

The rules are organized into the following categories for error prevention:

Annotation & At-rule Rules: Prevent unknown annotations, at-rules, and their descriptors Block & Comment Rules: Detect empty blocks and comments
Custom Property Rules: Ensure proper custom property usage Declaration Rules: Prevent duplicate properties and invalid property values Font Rules: Validate font family declarations Function Rules: Ensure proper function syntax (especially calc) Keyframe Rules: Validate keyframe blocks and declarations Media Rules: Prevent invalid media queries and features Grid & Nesting Rules: Validate CSS Grid and nesting syntax General CSS Rules: Catch common CSS structural errors Property Rules: Detect unknown and deprecated properties Selector Rules: Validate selector syntax and pseudo-elements/classes String & Syntax Rules: Prevent invalid strings and syntax patterns

Usage Examples

Basic Stylelint Configuration:

{
  "extends": "stylelint-config-recommended"
}

Extending with Custom Rules:

{
  "extends": "stylelint-config-recommended", 
  "rules": {
    "at-rule-no-unknown": [
      true,
      { "ignoreAtRules": ["extends", "tailwind"] }
    ],
    "property-no-unknown": [
      true,
      { "ignoreProperties": ["composes"] }
    ]
  }
}

Programmatic Usage:

const stylelint = require('stylelint');
const config = require('stylelint-config-recommended');

// Use the configuration object directly
const result = await stylelint.lint({
  code: 'a { color: blue; }',
  config: config
});

Types

/**
 * Stylelint configuration object structure
 */
interface StylelintConfig {
  /** Rule configurations keyed by rule name */
  rules: {
    [ruleName: string]: boolean | [boolean, any] | any;
  };
}

/**
 * Rule configuration value types
 */
type RuleConfig = 
  | boolean                    // Simple enable/disable
  | [boolean, RuleOptions]     // Enable/disable with options
  | RuleOptions;               // Options only (implies enabled)

interface RuleOptions {
  [key: string]: any;
}