En el artículo anterior ofrecimos diversos mecanismos para la incorporación de código JavaScript en los sitios web estáticos que creamos mediante el SSG Eleventy. Si tienes un javascript medianamente sencillo probablemente serán suficientes para ti, pero sí quieres incorporar frameworks o bibliotecas de código modernas desde npm probablemente necesites algo más.

Así pues, en este artículo vamos a ver una alternativa extra y mucho más versátil para incorporar nuestro código JS que aporta diversas ventajas, entre ellas el compilado del código JavaScript o el uso de packages npm importados por el nombre. Estas son tareas muy habituales en el desarrollo frontend moderno pero para poder llevarlas a cabo necesitamos alguna herramienta frontend. Una de las alternativas más populares actualmente es Vite, que nos permitirá realizar tareas habituales en las aplicaciones frontend y conseguirá optimizar el sitio web resultante.

Si no conoces Vite, cabe decir que es una herramienta que permite el procesamiento del código frontal, como el CSS o el JavaScript. Hemos abordado esta utilidad en otros artículos por lo que te recomendamos consultar la página de Vite.

Plugin de Eleventy para Vite

Para facilitar la integración entre Eleventy y Vite existe un plugin que podemos usar y que permite efectuar tanto las tareas de desarrollo como las de llevar el código a producción.

El plugin que veremos se llama eleventy-plugin-vite. Nos ahorrará mucho trabajo de integración de esta herramienta en los procesos de trabajo con el generador de sitios estáticos.

En realidad existen algunas aproximaciones para el uso de Vite en Eleventy. La que vamos a ver es la integración oficial de Vite realizada por el equipo de 11ty.

Actualización: En este artículo se verá un par de maneras de integrar el plugin eleventy-plugin-vite, que funcionan tanto en Eleventy 2.x como en 3.x, ya que la manera en la que lo había integrado en un sitio con Eleventy 2.x la he tenido que cambiar al actualizar el proyecto a Eleventy 3.0.

Vamos a ver al principio mis pasos de integración que usaba en Eleventy 2.x con éxito, ya que son más explicativos. Muchos coinciden exactamente a cómo vas a trabajar con Eleventy 3.x, ya que en el fondo son pequeños detalles los que he tenido que cambiar, uno de ellos el modo de trabajo con los módulos de JS, ya sea uses ESModules o CommonJS tradicionales de Node.

Pasos para integrar eleventy-plugin-vite en nuestro proyecto (Versión 2.x)

Ahora vamos a describir con detalle todos los pasos que necesitas realizar para integrar Vite en un proyecto de sitio estático generado con Eleventy.

Paso 1: Instalación del plugin Eleventy-Vite

Esto lo consigues con el siguiente comando de npm.

npm install @11ty/eleventy-plugin-vite

Paso 2: declaración del plugin en la configuración de Eleventy

A continuación necesitamos añadir el plugin en la configuración de Eleventy. Esto lo tenemos que hacer mediante el siguiente código en el archivo eleventy.config.js.

const EleventyVitePlugin = require("@11ty/eleventy-plugin-vite");

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(EleventyVitePlugin);
  // otras configuraciones
};

Paso 3: Donde colocar los archivos CSS y JavaScript

Para usar Vite en Eleventy, los archivos estáticos como CSS y JavaScript generalmente se colocan en el directorio "public", que cuelga desde la raíz de tu proyecto.

Así pues, ahora en nuestro proyecto vamos a tener una carpeta "public" en la que colocaremos todos los archivos que Vite debe procesar. Por mantener un poco de orden, y proyectos tienden a tener múltiples archivos JavaScript y CSS, vamos a crear dos carpetas dentro de public:

• public/css: Donde colocaremos las hojas de estilo que queremos que Vite procese.
• public/js: Donde colocaremos todos los archivos de javascript del proyecto.

Los archivos que coloquemos en este directorio se sirven como si estuviesen directamente publicados en la ruta raíz "/".

Aquí podemos hacer unas aclaraciones para aplicar algunos detalles sobre cómo funciona Vite. Durante la etapa de desarrollo se copian tal cual los archivos que están en "public" al directorio de distribución, sin cambios. Vite se encarga de procesarlos internamente cuando se ejecutan en el navegador. Durante la construcción de los archivos para llevar a producción (el build) Vite se encarga de procesarlos y dejar as copias compiladas en la carpeta de distribución.

Es importante referenciar estos activos usando rutas absolutas en el código del template, como veremos en el siguiente paso.

Paso 4: Enlazar el script JavaScript raíz en el layout

Ahora, para que Vite pueda hacer su trabajo debemos de incluir el script JavaScript o CSS en el layout. Con eso estaremos informando a Vite cuáles son los archivos raíz desde donde tiene que empezar a realizar la compilación de los assets.

Generalmente tendremos un archivo JavaScript de inicio que contendrá los imports a todos los módulos javascript que necesitamos en nuestro sitio web. Con enlazar este archivo raíz será suficiente para que Vite se encargue de realizar toda la concatenación de los archivos de código JS y su correspondiente compilado.

Solo hay un detalle y es que para poder realizar imports dentro del código JavaScript la etiqueta <script> necesita tener el atributo type="module", ya que si no obtendremos un error al ejecutar la página.

<script src="/js/index.js" type="module"></script>

Como has podido comprobar las rutas de los archivos las hemos colocado absolutas desde la raíz, asumiendo que están en una carpeta "js". A pesar que nosotros hemos colocado la carpeta "js" dentro del directorio "public", la ruta no debe mencionar a "public".

Compilación del CSS con Vite en Eleventy

Lo más normal es que quieras procesar también el código CSS, permitiendo que se compacten todos los archivos de CSS en un único fichero, optimizando el rendimiento de tu proyecto. Pues bien, el mismo proceso que hemos explicado para Javascript también te sirve para poder compilar el CSS.

Aunque creo que no hace falta mucha explicación adicional, simplemente tendrás que:

• Alojar los arhivos CSS en la carpeta public (generalmente usarás una carpeta public/css donde colocarás un archivo principal y todos los parciales de CSS)
• Enlazar la hoja de estilos en el layout con la correspondiente etiqueta <link>

Mediante el proceso de compiado de Vite se encargará de unir todos los CSS importados desde el archivo CSS principal. Gracias al plugin de Vite para Eleventy no necesitas hacer nada adicioal para que se realice el correspondiente compilado del CSS.

Cómo integrar el plugin eleventy-plugin-vite en Eleventy 3

En Eleventy 3 la mayoría de las cosas que necesitas saber para poder integrar este plugin son las mismas que ya has aprendido con los pasos anteriores. Vamos a ir directamente a las diferencias.

Módulos CommonJS Vs ESModules

En Eleventy 3 en adelante se ha dado preferencia a los módulos basados en el estándar de Javascript, conocidos como los ESModules. Esto es un gran avance para los que venimos del lado del frontend, porque nos acerca el modo de desarrollar, pero para quienes ya administraban un proyecto de Eleventy y venías trabajando con un eleventy.config.js basado en commonjs verás que tienes que hacer alguna cosa extra.

Básicamente el cambio consiste en traerte el módulo como un import, tal como explican ahora en la documentación:

import EleventyVitePlugin from "@11ty/eleventy-plugin-vite";

export default function (eleventyConfig) {
	eleventyConfig.addPlugin(EleventyVitePlugin);
}

El único problema es si, como yo, sigues usando un archivo de configuración escrito en common.js en Eleventy 3, porque vienes de una versión más antigua, o porque prefieras usar commonjs en tu proyecto, cosa perfectamente posible. En este caso lo que tendrías que hacer es un import dinámico.

De este modo, en el archivo eleventy.config.js o eleventy.config.cjs (o incluso en el nuevo archivo de configuración .eleventy.cjs o similares) no podrás usar import de ESModules. En su defecto puedes usar un import dinámico.

module.exports = async function (eleventyConfig) {
	const EleventyPluginVite = (await import("@11ty/eleventy-plugin-vite")).default;

	eleventyConfig.addPlugin(EleventyPluginVite);
};

Como puedes ver, en vez de traerte el módulo previamente, tienes que hacer un import dinámico dentro de la función de configuración. Tendrás que hacer el await para que el resto del archivo espere a que tengas ese import realizado. Por tanto, tendrás que firmar como async la funcón de configuración.

Cómo definir el Javascript

En la versión anterior usábamos el directorio public para guardar los archivos de JS y CSS que queríamos que Vite compilase, pero por alguna razón ahora en Eleventy 3.0 no está funcionando como antes, por lo que vamos a usar otra estrategia.

Primero vamos a colocarlos en una ruta dentro de nuestra carpeta de los documentos. Como todo en Eleventy es configurable. En mi caso tengo está configuración en eleventy.config.cjs:

return {
    dir: {
      input: "docs",
      output: "_site",
    }
};

Esto quiere decir que mi carpeta principal para el input del sitio es "docs". Así que voy a crear en esa carpeta un directorio llamado "assets", donde colocaremos los archivos Javascript y los archivos CSS. Así que tendremos las carpetas docs/assets/js y docs/assets/css.

Allí colocarás tus archivos CSS y JS como desees, pero obviamente habrá uno que sirva como arranque y ese lo tendremos que enlazar en el layout.

Como enlazar el CSS y el Javascript en el layout

Enlazaremos el archivo de arranque de Javascript, algo como index.js (o cualquier otro archivo que tú prefieras usar), en el layout con un código como este:

<script type="module" src="/assets/js/index.js"></script>

Además del Javascript, ahora enlazamos el archivo de arranque CSS de una manera como esta:

<link rel="stylesheet" href="/assets/css/styles.css">

Copiar los assets en el paso de desarrollo

La configuración anterior te sería suficiente para hacer el build y todo funcionaría correctamente, pero en la etapa de desarrollo Vite también necesita hacer su trabajo. Para ello vamos a agregar un copiado de los assets por medio de estas dos líneas, que también colocaremos en el archivo de configuración de Eleventy.

eleventyConfig.addPassthroughCopy('docs/assets/js')
eleventyConfig.addPassthroughCopy('docs/assets/css')

addPassthroughCopy() se usa en un proyecto de Eleventy (11ty) para decirle que copie directamente la carpeta señalada por parámetro al directorio de salida (_site por defecto) sin procesarla ni modificarla. Vite funcionará después de hacer esa copia en el proyecto, compilando los assets en la etapa de desarrollo.

Con esto ya lo tendríamos integrado. Por supuesto, en vuestro caso podréis necesitar configuraciones específicas que podrías definir en el plugin de la manera en la que se muestra en la documentación.

Proyecto de referencia starter-kit de Eleventy + Vite

Quiero dejar señalado el proyecto de refenrencia que he usado para ver la integración de Eleventy con el plugin eleventy-plugin-vite y he seguido sus pasos principales para poder integrarlo en mi proyecto de documentación.

El proyecto en sí se llama Eleventy Plus Vite y puedes verlo para poder extraer otras ideas si fuera necesario para tu caso de integración de Vite en Eleventy.