StyleLint: Linter CSS

Revisión de errores o problemas

Escribir código CSS correctamente es difícil, y sobre todo cuando empezamos, es muy habitual que adquiramos malas prácticas que hagan que nuestro código CSS sea de peor calidad. Esto es un problema, ya que a medida que escribimos código CSS, tiende a crecer exponencialmente y se vuelve mucho más difícil de mantener.

¿Qué es StyleLint?

Existen unas herramientas llamadas linters, que se encargan de revisar nuestro código a medida que lo vamos escribiendo y nos avisan de posibles problemas y malas prácticas. StyleLint es el linter por excelencia de CSS, mediante el cuál podremos vigilar la calidad del código CSS escrito e ir adquiriendo mejores hábitos de escritura de CSS.

Instalación de StyleLint

Para comenzar la instalación de StyleLint simplemente escribimos lo siguiente desde una terminal de texto:

$ npm install --save-dev stylelint stylelint-config-standard

Esto instalará la herramienta y un paquete de configuración estándar llamado stylelint-config-standard en nuestro proyecto como dependencias de desarrollo.

Para comprobar que todo ha ido correctamente, podemos escribir lo siguiente, que nos dará la versión de stylelint instalada:

$ npx stylelint --version
14.12.1

Si es así, podemos continuar al siguiente apartado.

Si alguno de los comandos anteriores te da error, probablemente sea porque no tienes instalado (o bien configurado) NodeJS. En ese caso, te recomiendo seguir la guía de instalación de Node con NVM y/o aprender a utilizar NPM.

Configuración de StyleLint

Para utilizar nuestro linter CSS debemos escribir lo siguiente:

$ npx stylelint src/index.css
  • npx es una herramienta que ayuda al sistema a buscar el comando de Node
  • stylelint es el nombre del linter que vamos a iniciar
  • src/index.css es la ruta de nuestro archivo .css que vamos a analizar

Si lo ejecutamos en este punto, probablemente tengamos un error similar al siguiente:

$ npx stylelint src/index.css
Error: No configuration provided for /home/manz/project-name/src/index.css

Esto ocurre porque no hemos creado un archivo de configuración, que es necesario para utilizar la herramienta. Así pues, creamos un archivo .stylelintrc.json en la raíz del proyecto (al mismo nivel que el package.json, fuera de src/) e incluimos las siguientes lineas:

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

Esto significa que va a leer la configuración base del paquete que instalamos anteriormente llamado stylelint-config-standard, por lo que ya debería funcionar nuestro linter con unas reglas básicas definidas por este paquete.

Volvemos a ejecutar el siguiente comando:

$ npx stylelint src/index.css

src/index.css
2:4 ✖ Expected indentation of 2 spaces indentation
4:9 ✖ Expected single space after ":" declaration-colon-space-after

2 problems (2 errors, 0 warnings)

Si tenemos un fichero src/index.css con varias líneas de código CSS en él con algún tipo de error nos aparecerán los errores como podemos ver en el ejemplo anterior. En el caso de que el fichero src/index.css no tenga errores, no nos mostrará nada.

En el mensaje del ejemplo anterior, nos indica que existen dos errores:

  • En la línea 2, carácter 4, se esperaba una indentación de 2 espacios (y no es así)
  • En la línea 4, carácter 9, se esperaba un espacio después de : y no es así

Como puedes ver, estos son problemas de estilo de código (que afectan al programador que lee el código), pero no errores que eviten que el navegador muestre correctamente la página. El linter es interesante porque nos acostumbra a escribir correctamente el código, de modo que sea más fácil de leer.

Observa que al final de cada error, nos indica una palabra clave, que es el nombre de la regla que ha detectado error. Si tienes curiosidad sobre alguna, puedes buscarla en la lista de reglas de Stylelint.

El fichero .stylelintrc.json

El fichero .stylelintrc.json incluye la configuración que indica a StyleLint como debe comportarse. De momento, sólo hemos dicho que utilice la configuración heredada del paquete stylelint-config-standard, sin embargo, se pueden añadir más paquetes de configuración:

Paquete de configuración Descripción
stylelint-config-standard Configuración base estándar para CSS.
stylelint-config-standard-scss Configuración base estándar para Sass.
stylelint-config-prettier Desactiva reglas que puedan dar conflicto con Prettier.
stylelint-config-recommended-vue Configuración recomendada para CSS en Vue.
stylelint-config-idiomatic-order Reglas para usar orden idiomático de CSS.
stylelint-config-styled-components Configuración para uso con Styled Components.
stylelint-config-html Configuración para ficheros HTML, Vue, Svelte, Astro, PHP...

Por ejemplo, veamos como haríamos para soportar código del preprocesador Sass. Lo primero, instalamos el paquete correspondiente si está disponible:

npm install --save-dev stylelint-config-standard-scss

Una vez hecho, lo cargamos en el fichero de configuración correspondiente:

{
"extends": "stylelint-config-standard-scss"
}

Sintaxis personalizada

En algunos casos, puede que no exista un paquete de configuración para una sintaxis específica. En ese caso, podemos utilizar customSyntax para indicar una configuración personalizada y que se adapte el linter lo mejor posible:

{
"extends": "stylelint-config-standard",
"customSyntax": "postcss-syntax"
}

En este caso, postcss-syntax permite cambiar automáticamente de sintaxis, según la extensión del fichero utilizado. No te olvides de instalar el paquete postcss-syntax, así como otros como postcss-styled (styled-components), postcss-jsx (JSX o CSS-in-JS) o postcss-html (HTML, Vue, Astro, PHP...) según interese para soportar formatos más específicos.

Reglas de StyleLint

Paquetes como stylelint-config-standard o similares, no son más que una configuración predefinida que incluye un conjunto de reglas determinado. Las reglas son las normas que tiene StyleLint para detectar si algo es incorrecto o no. Existe una amplia lista de reglas de StyleLint, separadas por categorías.

Es posible que en nuestro caso, nos guste la configuración por defecto de stylelint-config-standard, sin embargo, no estemos de acuerdo con alguna de las reglas preconfiguradas. Si es así, nosotros podemos modificar ciertas reglas particulares y ajustarla a nuestros criterios en nuestro archivo .stylelintrc.json:

{
"extends": "stylelint-config-standard",
"rules": {
"indentation": 4,
"declaration-colon-newline-after": "always-multi-line"
}
}

Observa que en la propiedad rules, hemos definido la regla indentation a 4, por lo que obligamos a que el linter cambie la indentación de las propiedades a 4 espacios, independientemente de la que tenga en el paquete de configuración.

Lo mismo ocurre con la regla declaration-colon-newline-after definida al valor always-multi-line. Sobreescribirá el valor que tenía en el paquete de configuración stylelint-config-standard al que hemos definido nosotros.

Corregir CSS (Autofix)

Una vez hemos llegado hasta este punto, tenemos nuestro StyleLint funcionando desde una terminal. Sin embargo, no es cómodo abrir la terminal cada vez que queremos comprobar si hay errores en nuestro código CSS. Lo ideal sería que esta tarea la realizara nuestro editor de código como VSCode a medida que escribimos en nuestro fichero .css.

Para ello, instalaremos la extensión StyleLint para VSCode. Una vez hecho, pulsamos F1 y marcamos la opción Abrir configuración de Usuario (JSON). Nos aparecerá un fichero .json que es la configuración de VSCode, donde añadiremos lo siguiente:

{
/* ... */
"css.validate": false,
"scss.validate": false,
"less.validate": false,
"stylelint.enable": true,
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.stylelint": true
},
/* ... */
}

Vamos a explicar que hace cada una de ellas:

  • Las propiedades css.validate, scss.validate y less.validate desactivan el linter básico integrado en VSCode, ya que usaremos el de StyleLint.
  • La propiedad stylelint.enable activa el StyleLint en nuestro VSCode. Mostrará los errores en la pestaña "Problemas". Necesita la extensión.
  • La propiedad editor.formatOnSave hace posible formatear el documento cada vez que guardemos un fichero.
  • La propiedad editor.codeActionsOnSave determina que se hará cuando se guarde el fichero. En nuestro caso colocamos source.fixAll.stylelint a true, lo que hará que intente corregir los problemas automáticamente.

Esta última opción es la equivalente a escribir lo siguiente en la terminal:

$ npx stylelint src/index.css --fix

Ten en cuenta que, por ejemplo, editor.formatOnSave está en un ambito global, por lo tanto se ejecuta al guardar cualquier tipo de archivo. Si sólo quieres que ocurra con ficheros .css, escribimos lo siguiente:

{
/* ... */
"[css]": {
"editor.formatOnSave": true,
/* Otras propiedades */
},
/* ... */
}

En este caso, el formatOnSave sólo se activará para los archivos de tipo css. Otros formatos podrían ser [javascript], [html], [markdown], etc.

Tabla de contenidos