Cómo aplicar linting a tu CSS con Stylelint

El CSS desordenado es fácil de escribir y difícil de mantener. Propiedades mal escritas, selectores duplicados y convenciones inconsistentes se cuelan en las revisiones de código y se acumulan como deuda técnica. Stylelint resuelve esto detectando errores y aplicando estándares automáticamente — antes de que lleguen a producción.

Esta guía cubre todo lo que necesitas para poner en marcha el linting de CSS con Stylelint en tu proyecto hoy mismo.

¿Qué es Stylelint y por qué debe formar parte de tu flujo de trabajo?

Stylelint es un linter de CSS con más de 100 reglas integradas, utilizado por equipos de Google y GitHub. Analiza estáticamente tus archivos CSS y reporta problemas — sintaxis inválida, propiedades desconocidas, selectores duplicados y violaciones de convenciones — sin ejecutar el código.

Una distinción importante: Stylelint se ocupa de la calidad del código, no del formato. No competirá con Prettier por espaciados o puntos y comas. Las dos herramientas son complementarias. Prettier formatea, mientras que Stylelint hace cumplir la corrección y la consistencia. Usa ambas.

Instalando Stylelint: dos formas de empezar

Stylelint requiere una versión moderna de Node.js (Node 20.19.0 o más reciente en las últimas versiones), así que asegúrate de que tu entorno esté actualizado.

Opción 1: Configuración automatizada (Recomendada)

La forma más rápida de aplicar linting a CSS con Stylelint es el comando create:

npm create stylelint@latest

Esto genera un archivo de configuración e instala stylelint-config-standard automáticamente. También funciona con pnpm, Yarn y Bun:

pnpm create stylelint
bun create stylelint

Opción 2: Configuración manual de Stylelint

Si prefieres tener el control total, instala las dependencias por tu cuenta:

npm add -D stylelint stylelint-config-standard

Luego crea un archivo stylelint.config.mjs en la raíz de tu proyecto:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"]
};

La extensión .mjs utiliza ESM — el formato de módulos moderno. Stylelint admite configuración ESM, que es el enfoque recomendado en las configuraciones actuales.

Ejecutando Stylelint en tus archivos CSS

Una vez instalado, ejecuta Stylelint sobre todos los archivos CSS:

npx stylelint "**/*.css"

Verás una salida como esta para cualquier violación:

src/main.css
  12:3  ✖  Unexpected duplicate selector ".btn"   no-duplicate-selectors
  24:5  ✖  Unknown property "colour"              property-no-unknown

Para corregir automáticamente lo que se pueda corregir, agrega el flag --fix:

npx stylelint "**/*.css" --fix

No todas las reglas admiten corrección automática, pero muchas sí. El flag --fix aplica correcciones seguras cuando es posible, pero no resolverá todos los problemas.

Configurando las reglas de linting de CSS en Stylelint

stylelint-config-standard es una base sólida. Puedes extenderla y sobrescribir reglas específicas en tu configuración:

/** @type {import('stylelint').Config} */
export default {
  extends: ["stylelint-config-standard"],
  rules: {
    "color-no-invalid-hex": true,
    "unit-no-unknown": true,
    "selector-id-pattern": null  // disable a rule
  }
};

Las reglas aceptan true para activarlas, null para desactivarlas, o un array para configurar la severidad:

"color-no-invalid-hex": [true, { severity: "warning" }]

Esto resulta útil cuando introduces Stylelint en una base de código existente — las advertencias te permiten auditar problemas sin bloquear las compilaciones de inmediato.

Agregando un script de lint a package.json

Integra Stylelint en tu flujo de trabajo con un script de npm:

{
  "scripts": {
    "lint:css": "stylelint \"**/*.css\""
  }
}

Ejecútalo con npm run lint:css. A partir de aquí, puedes integrarlo en tu pipeline de CI o en hooks pre-commit usando lint-staged y Husky.

Buenas prácticas para el linting de CSS

• Comienza con stylelint-config-standard — refleja las mejores prácticas actuales de CSS y se mantiene activamente.
• Utiliza advertencias antes que errores al adoptar Stylelint en código heredado.
• Ignora archivos generados añadiendo un archivo .stylelintignore (similar a .gitignore).
• Combínalo con Prettier — no intentes usar Stylelint para el formato.
• Ejecútalo en CI — el linting que solo corre en máquinas locales termina por omitirse.

Conclusión

Stylelint tarda unos cinco minutos en configurarse y devuelve el favor de inmediato detectando errores y manteniendo un código consistente. Instálalo, extiende stylelint-config-standard, agrega un script y ejecútalo. Esa es toda la configuración. Todo lo demás — reglas personalizadas, soporte para SCSS, integración con el IDE — se construye sobre esta base.

Preguntas frecuentes

Complete picture for complete understanding

Capture every clue your frontend is leaving so you can instantly get to the root cause of any issue with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data.

Check our GitHub repo and join the thousands of developers in our community.