A Stylelint Configuration for Tailwind CSS

[theenoahmason]

Hello Tailwind gang. We just published a Tailwind CSS Stylelint config that actually implements Tailwind CSS, rather than ignoring its functions and directives. Check it out!

• GitHub - https://github.com/dreamsicle-io/stylelint-config-tailwindcss
• NPM - https://www.npmjs.com/package/@dreamsicle.io/stylelint-config-tailwindcss

Copying some of the documentation below for reference:

Stylelint Config: Tailwind CSS

A Stylelint configuration for Tailwind CSS projects. This config was developed specifically for Tailwind CSS v4+ and Stylelint v16.17+. This configuration was developed because most of the other popular Stylelint configurations for Tailwind CSS simply ignore directives and functions. Instead, this config implements all Tailwind CSS directives and functions as syntax for Stylelint's language options; so not only can you use them without Stylelint complaining, but Stylelint will actually help to ensure you are using them correctly.

We generate only the syntax needed to override Stylelint's language options to support Tailwind CSS functions and directives. We've added all current Tailwind CSS at-rules, <--spacing()> and <--alpha> function definitions; and we added <tailwindcss-length> to replace <length>, and <tailwindcss-color> to replace <color>, which instructs stylelint where the spacing and alpha functions can be used respectively. This works by discovering replacement candidates and upgrading syntax from CSS Tree, which is the same package Stylelint uses under the hood.

This is accomplished using our SyntaxGenerator class, used through a Rollup plugin. The contents of these files are built to the syntax directory, then imported and built through rollup into an ESM module and a Common JS module located in the dist directory.

The contents of these files are passed to Stylelint's languageOptions.syntax through the config template found at src/stylelint.config.mjs. The generation of types, properties, and at-rules allows for automatic upgrading of CSS syntax to accept Tailwind CSS properties where they are accepted in the least destructive and most maintainable way possible.

We use a pretty robust set of tests: tests.css

Exports

This package exports both an ESM module and a Common JS module. The default export is the ESM module.

• dist/stylelint.config.mjs - ESM
• dist/stylelint.config.cjs - Common JS

Getting started

Install the package

npm install --save-dev @dreamsicle.io/stylelint-config-tailwindcss

Include in your Stylelint config

/**
 * @type {import("stylelint").Config}
 */
const stylelintConfig = {
	extends: [
		"stylelint-config-standard",
		"@dreamsicle.io/stylelint-config-tailwindcss",
	],
};

export default stylelintConfig;

Accessing specific keys

You can also decide to spread the imported config onto your stylelint object to extend languageOptions, languageOptions.syntax, languageOptions.syntax.types, languageOptions.syntax.properties, or languageOptions.syntax.atRules. Below is an example of how to fully spread everything provided by this config.

import configTailwindcss from "@dreamsicle.io/stylelint-config-tailwindcss/dist/stylelint.config.mjs";

/**
 * @type {import("stylelint").Config}
 */
const stylelintConfig = {
	extends: [
		"stylelint-config-standard",
	],
	languageOptions: {
		...configTailwindcss.languageOptions,
		syntax: {
			...configTailwindcss.languageOptions.syntax,
			types: {
				...configTailwindcss.languageOptions.syntax.types,
			},
			properties: {
				...configTailwindcss.languageOptions.syntax.properties,
			},
			atRules: {
				...configTailwindcss.languageOptions.syntax.atRules,
			},
		}
	},
	rules: {
		...configTailwindcss.rules,
		
	}
};

export default stylelintConfig;

Note: All types, properties, and at-rules and Stylelint rules are required for this configuration to funciton properly. There are no stylistic rules provided by it, as it inly includes what is needed to make Stylelint play well with Tailwind CSS.

[theenoahmason]

Just released v1.1.2.

• Relaxes types on @utility, @apply, and @custom-variant directives to comply with complex patterns that are valid Tailwind, that can't necessarily be represented with Stylelint's language options.