@kitschpatrol/stylelint-config

Stylelint configuration for @kitschpatrol/shared-config.

Overview

It's a shared Stylelint config, plus a command-line tool ksc-stylelint to perform Stylelint-related project initialization, linting, and fixing.

[!IMPORTANT]

You can use this package on its own, but it's recommended to use @kitschpatrol/shared-config instead for a single-dependency and single-package approach to linting and fixing your project.

This package is included as a dependency in @kitschpatrol/shared-config, which also automatically invokes the command line functionality in this package via its ksc command

Setup

To use just this Stylelint config in isolation:

1. Install the basic repository configuration files in your project root. This is required for correct PNPM behavior:

   pnpm --package=@kitschpatrol/repo-config dlx ksc-repo init

2. Add the package:

   pnpm add -D @kitschpatrol/stylelint-config

3. Add the starter stylelint.config.js file to your project root, and add any customizations you'd like:

   pnpm exec ksc-stylelint init

Rules

• stylelint-config-recommended (Rules)
• stylelint-config-standard (Extends the above with additional rules)
• stylelint-config-clean-order
• stylelint-config-html (Parses HTML, XML, Vue, Svelte, Astro, and PHP files)
• stylelint-plugin-defensive-css (Recommended preset for defensive and accessible CSS)
• Additional customizations

Usage

The Stylelint binary should be picked up automatically by VS Code plugins.

You can call it directly, or use the script bundled with the config.

Integrate with your package.json scripts as you see fit, for example:

{
  "scripts": {
    "lint": "ksc-stylelint lint",
    "fix": "ksc-stylelint fix"
  }
}

Configuration

To create a stylelint.config.js in your project root:

pnpm exec ksc-stylelint init

(Note that this will delete the stylelint property in your package.json!)

Or

To create a stylelint property in package.json:

pnpm exec ksc-stylelint init --location package

(Note that this will delete the stylelint.config.js file in your project root!)

Ignoring files

Ignores all files in .gitignore by default.

Additional tool-specific ignores may be added to the config via the ignoreFiles key.

Ignoring code

See the Stylelint documentation.

Blocks:

/* stylelint-disable */ ... /* stylelint-enable */

Inline:

/* stylelint-disable-line */

Next line:

/* stylelint-disable-next-line

CLI

Command: ksc-stylelint

Kitschpatrol's Stylelint shared configuration tools.

This section lists top-level commands for ksc-stylelint.

Usage:

ksc-stylelint <command>

| Command | Argument | Description | | -------------- | ----------- | -------------------------------------------------------------------------------------------------------------------- | | init | | Initialize by copying starter config files to your project root or to your package.json file. | | lint | [files..] | Lint your project with Stylelint. Matches files below the current working directory by default. | | fix | [files..] | Fix your project with Stylelint. Matches files below the current working directory by default. | | print-config | [file] | Print the effective Stylelint configuration. Package-scoped by default, file-scoped if a file argument is provided.. |

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

See the sections below for more information on each subcommand.

Subcommand: ksc-stylelint init

Initialize by copying starter config files to your project root or to your package.json file.

Usage:

ksc-stylelint init

| Option | Description | Type | Default | | ------------------- | --------------------------------- | -------------------- | -------- | | --location | Where to store the configuration. | "file" "package" | "file" | | --help-h | Show help | boolean | | | --version-v | Show version number | boolean | |

Subcommand: ksc-stylelint lint

Lint your project with Stylelint. Matches files below the current working directory by default.

Usage:

ksc-stylelint lint [files..]

| Positional Argument | Description | Type | Default | | ------------------- | ------------------------------ | ------- | ---------------------------------------------------------- | | files | Files or glob pattern to lint. | array | "**/*.{css,scss,sass,svelte,html,astro,tsx,jsx,php,vue}" |

| Option | Description | Type | Default | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------- | | --format | Output format: "native" streams each tool's own output, "machine" prints one parseable line per issue for editor problem matchers, "json" prints an aggregate report. | "json" "machine" "native" | "native" | | --cache | Use tool-native caches stored below node_modules/.cache/ksc at the workspace root. Disable with --no-cache. | boolean | true | | --help-h | Show help | boolean | | | --version-v | Show version number | boolean | |

Subcommand: ksc-stylelint fix

Fix your project with Stylelint. Matches files below the current working directory by default.

Usage:

ksc-stylelint fix [files..]

| Positional Argument | Description | Type | Default | | ------------------- | ----------------------------- | ------- | ---------------------------------------------------------- | | files | Files or glob pattern to fix. | array | "**/*.{css,scss,sass,svelte,html,astro,tsx,jsx,php,vue}" |

| Option | Description | Type | Default | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ---------- | | --format | Output format: "native" streams each tool's own output, "machine" prints one parseable line per issue for editor problem matchers, "json" prints an aggregate report. | "json" "machine" "native" | "native" | | --cache | Use tool-native caches stored below node_modules/.cache/ksc at the workspace root. Disable with --no-cache. | boolean | true | | --help-h | Show help | boolean | | | --version-v | Show version number | boolean | |

Subcommand: ksc-stylelint print-config

Print the effective Stylelint configuration. Package-scoped by default, file-scoped if a file argument is provided..

Usage:

ksc-stylelint print-config [file]

| Positional Argument | Description | Type | | ------------------- | ------------------------------------------------ | -------- | | file | File or glob pattern to print configuration for. | string |

| Option | Description | Type | | ------------------- | ------------------- | --------- | | --help-h | Show help | boolean | | --version-v | Show version number | boolean |

VS Code tasks

ksc-stylelint init adds a .vscode/tasks.json with two tasks:

• ksc-stylelint lint runs ksc-stylelint lint --format machine across the whole project
• ksc-stylelint fix runs ksc-stylelint fix --format machine, applying auto-fixes and reporting whatever couldn't be fixed

If you're using the complete @kitschpatrol/shared-config package, you'd more likely want to run:

• ksc lint runs ksc lint --format machine, which runs all ksc lint tools across the whole project
• ksc fix runs ksc fix --format machine, which applies all ksc fix auto-fixes and reports anything unfixable

Run them via the Tasks: Run Task command (or the Terminal → Run Task… menu item).

Each task's problem matcher parses the machine-format output and populates VS Code's Problems panel with every reported issue, pointing to the offending file, line, and column.

The tasks share a problem matcher owner with the other @kitschpatrol/shared-config tasks, so the panel reflects the most recent run rather than stacking duplicates.

If your project already has a .vscode/tasks.json, init merges by task label: your own tasks are left alone, and same-label tasks are replaced with the latest definitions.

API

The package also exports fix, fixFile functions for linting and fixing CSS programmatically, pre-configured with the shared Stylelint configuration.

import { clearCache, fix, fixFile } from '@kitschpatrol/stylelint-config'

// Fix a CSS string
const fixed = await fix('a { color: rgb(0, 0, 0); }\n')

// Fix with a bare file extension for syntax inference
const scss = await fix(source, 'scss')

// Fix with config overrides
const withOverrides = await fix(source, { rules: { 'color-hex-length': 'long' } })

// Both file type and config overrides
const both = await fix(source, 'scss', { rules: { 'color-hex-length': 'long' } })

// Fix a file in place
await fixFile('./src/styles.css')

// Clear cached Stylelint module
clearCache()

Config is resolved in priority order: shared defaults < per-call overrides.

The Stylelint module is cached internally for performance across multiple calls. Use clearCache() to force re-initialization.

License

MIT © Eric Mika