eslint-plugin-css-custom-properties

1.1.0 verified Fri May 01 auth: no javascript

ESLint plugin to lint CSS custom properties (CSS variables) in JavaScript template literals and strings. Version 1.1.0, released under MIT. Currently in active development with moderate release cadence. It focuses on detecting unknown, unused, or misused CSS custom properties within JavaScript code, which is useful for projects using CSS-in-JS or template literals for styling. Unlike generic CSS linting tools, this plugin operates inside JS strings, supporting ESLint >=7. Requires Node.js ^14.17.0 || ^16.0.0 || >= 18.0.0.

Common errors

error Error: Failed to load plugin 'css-custom-properties' declared in '.eslintrc': Cannot find module 'eslint-plugin-css-custom-properties' ↓

cause Plugin not installed or not in node_modules.

fix

Run npm install eslint-plugin-css-custom-properties --save-dev

error TypeError: Cannot read properties of undefined (reading 'no-unknown') ↓

cause Using require() on the plugin's rules directly while the package is ESM-only.

fix

Use import instead: import { rules } from 'eslint-plugin-custom-properties' or configure the plugin with plugin name in plugins array.

error ESLint configuration error: Configuration for rule 'css-custom-properties/no-unknown' is invalid ↓

cause Rule severity set to a number but rule expects 'off', 'warn', or 'error'.

fix

Use string values: 'error' instead of 2, etc.

Warnings

breaking ESM-only: dropping CJS support in v1.1.0 ↓

fix Use import instead of require; update Node to >=14.17.0 or >=16.0.0 or >=18.0.0.

gotcha Rule names must be prefixed with 'css-custom-properties/' in ESLint config ↓

fix Use 'css-custom-properties/no-unknown' instead of just 'no-unknown'.

gotcha Plugin ignores CSS custom properties in regular CSS files; only processes strings in JS/TS files ↓

fix Ensure you have eslint-plugin-css-custom-properties in the plugins array and run ESLint on JS/TS files containing template literals with CSS.

deprecated Some rule configurations may change between minor versions; check changelog ↓

fix Pin dependency version if using programmatic rule options.

Install

npm install eslint-plugin-css-custom-properties

yarn add eslint-plugin-css-custom-properties

pnpm add eslint-plugin-css-custom-properties

Imports

rules

wrong

const rules = require('eslint-plugin-css-custom-properties/rules')

correct

import { rules } from 'eslint-plugin-css-custom-properties'

ESM-only since v1.1.0; the package exports 'rules' for programmatic use.

configs

wrong

const configs = require('eslint-plugin-css-custom-properties').configs

correct

import { configs } from 'eslint-plugin-css-custom-properties'

Available for predefined rule configurations.

plugin

wrong

const plugin = require('eslint-plugin-css-custom-properties')

correct

import plugin from 'eslint-plugin-css-custom-properties'

Default export provides the plugin object with rules and configs.

Quickstart

Configures ESLint to lint CSS custom properties in JavaScript strings and shows a lint error for unknown variables.

// .eslintrc.cjs
module.exports = {
  plugins: ['css-custom-properties'],
  rules: {
    'css-custom-properties/no-unknown': 'error',
  },
};

// Check a file with unknown custom property
const styles = `
  color: var(--unknown-var);
`;
// This will trigger a lint error if --unknown-var is not defined in CSS