A7. npm, Vite y librerías de terceros

En esta actividad crearemos una aplicación web con Vanilla JavaScript que utilizará Chart.js, una librería de terceros para representar datos mediante gráficos.

Utilizaremos Node.js, npm y Vite para gestionar el proyecto y sus dependencias. Finalmente, compilaremos la aplicación y la publicaremos en GitHub Pages mediante GitHub Actions.

Documentación de la actividad

Documenta cada apartado conforme lo realizas en el repositorio de actividades de DWEC.

Incluye los comandos utilizados, las respuestas a las cuestiones planteadas y las capturas de pantalla solicitadas para demostrar los resultados obtenidos.

1. Node.js y npm

Node.js es un entorno de ejecución que permite ejecutar JavaScript fuera del navegador. Gracias a Node.js podemos utilizar herramientas de desarrollo como Vite.

npm es un gestor de paquetes de JavaScript que se distribuye habitualmente con Node.js. También proporciona acceso al registro público de npm, donde podemos encontrar librerías y herramientas desarrolladas por terceros.

Desde el terminal, comprueba las versiones instaladas:

node --version
npm --version

Realiza una captura del terminal donde se vean las versiones de Node.js y npm.

Explica brevemente la diferencia entre Node.js y npm y las ventajas de utilizar paquetes de terceros en nuestros proyectos.

Documentación

Comprueba que has incluido:

1. La captura del terminal con las versiones de Node.js y npm.
2. La diferencia entre Node.js y npm.
3. Las ventajas de utilizar paquetes de terceros.

2. Proyectos npm

npm permite gestionar proyectos JavaScript mediante un archivo llamado package.json, que contiene información sobre el proyecto, sus dependencias y los comandos disponibles.

Inicializar un proyecto

Crea un directorio llamado npm-test y accede a él:

mkdir npm-test
cd npm-test

Ejecuta:

npm init

Este comando permite inicializar un proyecto npm y crear su archivo package.json.

Durante la ejecución, npm solicita información como el nombre del proyecto, su versión, descripción y punto de entrada.

Introduce los valores que consideres adecuados y comprueba que se ha generado package.json.

Abre el archivo y examina sus propiedades. Realiza una captura de package.json donde se vean sus propiedades iniciales.

npm init -y

El comando:

npm init -y

Permite crear package.json directamente, aceptando los valores predeterminados sin realizar preguntas.

Instalar dependencias

Las dependencias son paquetes externos que utilizamos en nuestros proyectos.

En package.json se distinguen principalmente:

• dependencies: paquetes necesarios para el funcionamiento de la aplicación.
• devDependencies: herramientas utilizadas durante el desarrollo, las pruebas o la compilación.

Instala Chart.js como dependencia:

npm install chart.js

Comprueba que aparece en el apartado dependencies de package.json.

Ahora instala Vite como dependencia de desarrollo:

npm install --save-dev vite

--save-dev

La opción --save-dev, equivalente a -D, indica a npm que registre el paquete en devDependencies en lugar de dependencies.

Comprueba que Vite aparece en devDependencies.

Realiza una captura de package.json donde aparezcan Chart.js en dependencies y Vite en devDependencies.

Observa también que se han generado:

• node_modules/: directorio que contiene los paquetes instalados y sus dependencias.
• package-lock.json: archivo que registra las versiones exactas y la resolución de las dependencias instaladas.

Realiza una captura de la estructura del proyecto donde se vean package.json, package-lock.json y node_modules/.

Explica brevemente para qué sirve cada uno de estos tres elementos y cuál es la diferencia entre dependencies y devDependencies.

Documentación

Comprueba que has incluido:

1. Los comandos utilizados para crear el proyecto e instalar los paquetes.
2. Las capturas de package.json antes y después de instalar las dependencias.
3. La captura de la estructura del proyecto.
4. La finalidad de los archivos y directorios generados y la diferencia entre los dos tipos de dependencias.

Este proyecto es únicamente de prueba. En el siguiente apartado crearemos otro proyecto utilizando el generador de Vite.

3. Crear el proyecto con Vite

Vite es una herramienta que proporciona un servidor de desarrollo y permite compilar una aplicación web para su publicación.

Entre sus funcionalidades destacan:

• Servidor de desarrollo con actualización rápida de los cambios.
• Soporte de módulos JavaScript.
• Resolución de las importaciones de paquetes npm.
• Compilación y optimización de archivos para producción.

Crea un nuevo proyecto:

npm create vite@latest

¿Qué hace este comando?

npm create vite@latest utiliza el mecanismo de inicialización de npm para ejecutar el generador create-vite en su versión más reciente.

Este generador crea la estructura inicial del proyecto y su archivo package.json, donde Vite aparece declarado como dependencia de desarrollo.

Después utilizaremos npm install para instalar las dependencias.

Durante la configuración:

1. Introduce un nombre para el proyecto, por ejemplo npm-chart.
2. Selecciona Vanilla como framework.
3. Selecciona JavaScript como variante.

Accede al directorio creado:

cd npm-chart

Instala las dependencias:

npm install

Comprueba que ahora existen:

• package.json.
• package-lock.json.
• node_modules/.

Realiza una captura de la estructura del proyecto donde se vean estos tres elementos.

Archivos de npm

package.json describe el proyecto y declara sus dependencias.

package-lock.json registra las versiones exactas y la resolución del árbol de dependencias, facilitando instalaciones reproducibles.

node_modules/ contiene los paquetes instalados y sus dependencias.

Abre package.json y localiza:

• name.
• version.
• type.
• scripts.
• dependencies, si existe.
• devDependencies.

Realiza una captura de package.json donde se identifiquen sus principales propiedades y Vite como dependencia de desarrollo.

Comprueba en qué apartado aparece Vite.

Consulta también el contenido de package-lock.json y localiza el directorio correspondiente a Vite dentro de node_modules/.

Explica brevemente la finalidad de package-lock.json y node_modules/.

Versión de Node.js

Crea un archivo .nvmrc en la raíz del proyecto.

Introduce la versión principal de Node.js que estés utilizando, por ejemplo:

22

.nvmrc

El archivo .nvmrc indica qué versión de Node.js debe utilizarse en el proyecto con herramientas compatibles como nvm.

El comando nvm use permite seleccionar esa versión, siempre que esté instalada.

Comprueba el funcionamiento de nvm use y verifica la versión activa mediante node --version.

Realiza una captura del terminal donde se vea la versión de Node.js después de ejecutar nvm use.

Explica para qué sirve el archivo .nvmrc.

Documentación

Comprueba que has incluido:

1. Los comandos utilizados para crear el proyecto e instalar las dependencias.
2. Las capturas de la estructura del proyecto y de package.json.
3. La explicación de package-lock.json y node_modules/.
4. La captura de la versión de Node.js después de ejecutar nvm use.
5. La explicación de la finalidad de .nvmrc.

4. Preparar el proyecto

La plantilla inicial de Vite contiene archivos de ejemplo que no necesitaremos.

Elimina los archivos y recursos de demostración, conservando la estructura necesaria para nuestro proyecto.

La parte principal deberá quedar así:

npm-chart/
├── public/
│   └── vite.svg
├── src/
│   └── main.js
├── .gitignore
├── .nvmrc
├── index.html
├── package.json
├── package-lock.json
└── node_modules/

El archivo vite.svg es opcional y puede conservarse como favicon.

Realiza una captura de la estructura del proyecto después de eliminar los archivos de ejemplo.

Sustituye el contenido de index.html por:

<!doctype html>
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Chart.js con Vite</title>
    <script type="module" src="/src/main.js"></script>
  </head>

  <body>
    <h1>Gráfico con Chart.js</h1>

    <div style="width: 600px">
      <canvas id="myChart"></canvas>
    </div>
  </body>
</html>

Deja src/main.js vacío por el momento.

Punto de partida

index.html es el documento HTML principal de la aplicación.

Desde él se carga src/main.js mediante una etiqueta <script type="module">.

Vite utiliza estos archivos como punto de partida para ejecutar y compilar la aplicación.

Ejecuta el servidor de desarrollo:

npm run dev

Abre la dirección indicada por Vite y comprueba que aparece el título de la página.

Realiza una captura del navegador donde se vea la página inicial.

Explica brevemente la relación entre index.html y src/main.js.

Documentación

Comprueba que has incluido:

1. La captura de la estructura del proyecto preparado.
2. La captura de la página inicial en el navegador.
3. La explicación de la relación entre index.html y src/main.js.

5. Investigar Chart.js

Accede a los siguientes recursos:

• Web oficial de Chart.js.
• Registro npm.
• Repositorio de Chart.js en GitHub.

Busca el paquete chart.js desde el buscador de npm.

En la web oficial, investiga para qué sirve Chart.js y qué tipos de gráficos permite crear. Resume tus conclusiones.

En npm, localiza el número aproximado de descargas semanales del paquete. Anota la cifra y realiza una captura donde se vea.

Consulta la última versión publicada y su fecha de publicación. Anota ambos datos y realiza una captura de la información consultada.

Accede al repositorio de GitHub y examina su actividad reciente. Realiza una captura donde se pueda comprobar dicha actividad.

A partir de la información recopilada, razona si Chart.js es una librería utilizada y mantenida actualmente.

Documentación

Comprueba que has incluido:

1. La explicación de la finalidad de Chart.js y los tipos de gráficos disponibles.
2. El dato y la captura de las descargas semanales.
3. La versión, la fecha de publicación y su captura.
4. La captura de la actividad del repositorio de GitHub.
5. La valoración razonada sobre su utilización y mantenimiento.

6. Instalar y utilizar Chart.js

Instala Chart.js desde el terminal:

npm install chart.js

Abre package.json y comprueba que ahora aparecen dos apartados:

• dependencies, con Chart.js.
• devDependencies, con Vite.

Realiza una captura de package.json donde aparezcan Chart.js en dependencies y Vite en devDependencies.

Localiza también el directorio del paquete Chart.js dentro de node_modules/. Realiza una captura de ese directorio.

Importación de Chart.js

Sustituye el contenido de src/main.js por:

import Chart from "chart.js/auto";

const ctx = document.getElementById("myChart");

new Chart(ctx, {
  type: "bar",
  data: {
    labels: ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
    datasets: [
      {
        label: "# of Votes",
        data: [12, 19, 3, 5, 2, 3],
        borderWidth: 1,
      },
    ],
  },
  options: {
    scales: {
      y: {
        beginAtZero: true,
      },
    },
  },
});

Comprueba que aparece un gráfico de barras en el navegador y realiza una captura de su funcionamiento.

¿Cómo funciona la importación?

La primera línea:

import Chart from "chart.js/auto";

Importa la exportación predeterminada del módulo chart.js/auto y la identifica localmente como Chart.

Cuando ejecutamos npm install chart.js, npm descarga el paquete y sus dependencias al directorio node_modules/.

Posteriormente, Vite resuelve la importación para que podamos utilizar la librería desde main.js.

La instrucción:

new Chart(ctx, { ... });

Crea una nueva instancia del gráfico utilizando la clase importada.

Localiza el paquete en node_modules/chart.js, consulta su archivo package.json e identifica cómo declara sus exportaciones.

Responde y razona las siguientes cuestiones:

1. ¿Qué diferencia hay entre instalar un paquete con npm e importarlo desde JavaScript?
2. ¿Qué representa Chart dentro de main.js?
3. ¿Por qué no necesitamos incluir un <script> externo de Chart.js en index.html?
4. ¿Qué funciones diferentes desempeñan Vite y Chart.js?

Documentación

Comprueba que has incluido:

1. Las capturas de package.json, node_modules/chart.js y el gráfico funcionando.
2. Las respuestas sobre la instalación, la importación y el significado de Chart.
3. La explicación de por qué no se necesita un script externo y de las funciones de Vite y Chart.js.

7. Introducción al DOM

El DOM (Document Object Model) es una representación del documento HTML mediante objetos organizados en forma de árbol.

JavaScript puede acceder a estos objetos y modificar sus propiedades.

En index.html tenemos:

<canvas id="myChart"></canvas>

Y en main.js:

const ctx = document.getElementById("myChart");

Aquí:

• document representa el documento HTML.
• getElementById() es un método del DOM.
• "myChart" identifica el elemento que queremos localizar.
• ctx almacena una referencia al objeto que representa el elemento <canvas>.

Chart.js utiliza ese elemento para dibujar el gráfico.

Inspeccionar el objeto

Añade después de la declaración de ctx:

console.dir(ctx);

Abre las herramientas de desarrollo del navegador y examina el objeto mostrado en la consola.

Localiza la propiedad style. Realiza una captura de la consola donde se vea el objeto ctx y dicha propiedad.

Modifica el fondo del canvas:

ctx.style.backgroundColor = "lightblue";

Comprueba el resultado y cambia el color por otro diferente. Realiza una captura del gráfico con el nuevo color de fondo.

Canvas y Chart.js

El fondo del elemento <canvas> se modifica mediante el DOM y CSS.

El color de las barras, en cambio, se establece mediante las propiedades de configuración de Chart.js.

Son dos mecanismos diferentes.

Explica brevemente qué es el DOM, para qué sirve document.getElementById() y cuál es la diferencia entre modificar el fondo del canvas y el color de las barras.

Documentación

Comprueba que has incluido:

1. La captura de la consola con el objeto ctx y su propiedad style.
2. La captura del gráfico con el nuevo color de fondo.
3. La explicación del DOM, getElementById() y los dos mecanismos de modificación de colores.

8. Personalizar el gráfico

Examina el código de main.js e identifica:

• El tipo de gráfico.
• Las etiquetas de las barras.
• Los valores representados.
• El nombre de la serie de datos.
• Las opciones de configuración.

Identifica en tu documentación las propiedades del código que corresponden a cada elemento.

Modificar los datos

Cambia las etiquetas y los valores para representar datos diferentes.

Investiga en la documentación de Chart.js cómo modificar el color de las barras mediante la propiedad backgroundColor.

Realiza una captura del gráfico después de modificar sus datos iniciales y el color de las barras.

Crear una interfaz de configuración

Amplía index.html incorporando el siguiente formulario, que permitirá modificar las características del gráfico:

<h2>Configuración del gráfico</h2>

<form id="chartForm">
  <div>
    <label for="chartTitle">Nombre de la serie:</label>
    <input type="text" id="chartTitle" value="# of Votes" />
  </div>

  <div>
    <label for="barColor">Color de las barras:</label>
    <select id="barColor">
      <option value="red">Rojo</option>
      <option value="blue">Azul</option>
      <option value="green">Verde</option>
      <option value="orange">Naranja</option>
    </select>
  </div>

  <div>
    <label for="chartLabels">Etiquetas:</label>
    <input
      type="text"
      id="chartLabels"
      value="Red,Blue,Yellow,Green,Purple,Orange"
    />
  </div>

  <div>
    <label for="chartValues">Valores:</label>
    <input type="text" id="chartValues" value="12,19,3,5,2,3" />
  </div>

  <button type="button" id="updateChart">Actualizar gráfico</button>
</form>

El formulario contiene:

• Un campo de texto para modificar el nombre de la serie de datos.
• Un selector para elegir el color de las barras.
• Un campo de texto con las etiquetas separadas por comas.
• Un campo de texto con los valores numéricos separados por comas.
• Un botón para aplicar los cambios.

El objetivo es conseguir una interfaz similar a la siguiente:

Por ahora, el formulario no modificará el gráfico. Para conseguirlo, tendrás que implementar su funcionamiento desde main.js.

Realiza una captura de la interfaz de configuración que has creado.

Actualizar el gráfico

Para poder modificar el gráfico después de crearlo, almacena su instancia en una variable:

const chart = new Chart(ctx, {
  // Configuración del gráfico.
});

Investiga cómo modificar las propiedades de chart.data.

Por ejemplo, para cambiar el color de las barras:

chart.data.datasets[0].backgroundColor = "red";
chart.update();

El método update() actualiza el gráfico después de modificar sus datos o configuración. Explica brevemente por qué es necesario llamarlo después de cambiar las propiedades de chart.data.

Para implementar el funcionamiento del formulario:

1. Accede al botón mediante document.getElementById().
2. Utiliza addEventListener() para detectar el evento click sobre el botón.
3. Obtén los valores de los campos utilizando su propiedad value.
4. Convierte las cadenas de etiquetas y valores en arrays mediante split(",").
5. Convierte los valores numéricos utilizando Number().
6. Comprueba que el número de etiquetas coincide con el número de valores y que estos son numéricos.
7. Modifica las propiedades correspondientes de chart.data.
8. Ejecuta chart.update() para reflejar los cambios.

Comprueba que el gráfico se actualiza correctamente sin recargar la página. Realiza una captura después de actualizarlo mediante el botón.

Documentación

Comprueba que has incluido:

1. La identificación de las propiedades de configuración del gráfico.
2. La captura del gráfico con los datos y colores modificados.
3. La captura de la interfaz de configuración.
4. La captura del gráfico actualizado mediante el botón.
5. La explicación de la función de chart.update().

9. Compilar la aplicación

Hasta ahora hemos ejecutado la aplicación utilizando el servidor de desarrollo de Vite.

Para generar una versión preparada para producción, ejecuta:

npm run build

Vite generará el directorio dist/.

Realiza una captura del terminal donde se vea la ejecución correcta de npm run build.

Examínalo y localiza:

• El archivo index.html.
• Los archivos JavaScript generados.
• Los recursos estáticos que se hayan incluido.

Realiza una captura de la estructura de dist/ donde se vean los archivos generados.

Dependencias y compilación

Recuerda que:

• Chart.js es una dependencia utilizada por nuestra aplicación.
• Vite es una herramienta de desarrollo y compilación.

Durante el build, Vite procesa las importaciones y genera los archivos que necesita el navegador.

El código de Chart.js utilizado por nuestra aplicación se incorpora normalmente a los archivos JavaScript generados.

Sin embargo, Vite no se incluye como herramienta de desarrollo dentro de la aplicación publicada.

Esto no significa que todas las dependencias de desarrollo queden necesariamente excluidas del código generado: la distinción entre dependencies y devDependencies depende de la función que desempeñan los paquetes en el proyecto.

Compara los archivos fuente con los archivos generados en dist/ y responde razonadamente:

1. ¿Qué diferencias observas entre los archivos originales y los compilados?
2. ¿Por qué no aparece node_modules/ dentro de dist/?
3. ¿Por qué el navegador puede ejecutar la aplicación sin tener instalado Node.js ni npm?

Prueba la versión compilada mediante:

npm run preview

Comprueba que el gráfico y el formulario funcionan correctamente. Realiza una captura de la aplicación funcionando mediante npm run preview.

Documentación

Comprueba que has incluido:

1. La captura del terminal con el resultado de npm run build.
2. La captura de la estructura de dist/.
3. Las respuestas sobre las diferencias entre los archivos, la ausencia de node_modules/ y la ejecución en el navegador.
4. La captura de la aplicación funcionando con npm run preview.

10. Publicar en GitHub Pages

Publicaremos la aplicación mediante GitHub Actions, que permitirá compilar y desplegar el proyecto automáticamente.

El proceso será:

Proyecto local
     |
     v
GitHub (repositorio)
     |
     v
GitHub Actions
     |
     +-- Instalar dependencias
     |
     +-- Compilar con Vite
     |
     v
GitHub Pages
     |
     v
Aplicación publicada

Preparar Vite

GitHub Pages publica normalmente los repositorios de proyecto bajo una ruta como:

https://usuario.github.io/nombre-repositorio/

Por ello, Vite debe conocer la ruta base de publicación.

Crea vite.config.js en la raíz del proyecto:

import { defineConfig } from "vite";

export default defineConfig({
  base: "/npm-chart/",
});

Sustituye npm-chart por el nombre real de tu repositorio. Explica por qué la propiedad base debe coincidir con la ruta de publicación.

WARNING

La propiedad base debe coincidir con la ruta del repositorio en GitHub Pages.

Si se configura incorrectamente, los archivos JavaScript y otros recursos pueden no cargarse en la página publicada.

Preparar Git

Comprueba que .gitignore excluye, al menos:

node_modules/
dist/

Estos directorios no deben incorporarse normalmente al repositorio.

En cambio, deben versionarse:

• package.json.
• package-lock.json.
• .nvmrc.
• Los archivos fuente de la aplicación.
• La configuración de Vite.
• El workflow de GitHub Actions.

Sube el proyecto a tu repositorio de GitHub. Incluye la URL del repositorio en tu documentación.

Configurar GitHub Actions

En el repositorio, accede a:

Settings → Pages → Build and deployment → Source

Selecciona GitHub Actions. Realiza una captura de la configuración de GitHub Pages donde se vea el origen seleccionado.

Crea el archivo:

.github/workflows/deploy.yml

Con el siguiente contenido:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version-file: .nvmrc
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    needs: build

    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

npm ci

npm ci instala las dependencias a partir de package-lock.json, respetando las versiones registradas.

Es especialmente adecuado para entornos automatizados como GitHub Actions, porque permite realizar instalaciones reproducibles.

Comprobar el despliegue

Accede a la pestaña Actions del repositorio.

Comprueba que se ejecutan correctamente las fases de:

1. Descarga del repositorio.
2. Preparación de Node.js.
3. Instalación de dependencias.
4. Compilación con Vite.
5. Publicación en GitHub Pages.

Realiza una captura de la ejecución correcta del workflow donde se vean los trabajos de compilación y despliegue.

Cuando finalice, accede a la URL publicada y comprueba que la aplicación funciona correctamente. Anota la URL de la aplicación y realiza una captura de su funcionamiento en GitHub Pages.

Actualización automática

Modifica algún aspecto del gráfico y guarda los cambios.

Realiza un nuevo commit y súbelo a GitHub.

Comprueba que GitHub Actions inicia automáticamente una nueva ejecución y publica la versión actualizada. Realiza una captura de la nueva ejecución en la pestaña Actions.

Explica brevemente las diferencias entre GitHub, GitHub Actions y GitHub Pages.

Documentación

Comprueba que has incluido:

1. Las URL del repositorio y de la aplicación publicada.
2. La explicación de la propiedad base de Vite.
3. La captura de la configuración de GitHub Pages.
4. Las capturas de la ejecución correcta del workflow y de la aplicación publicada.
5. La captura de la nueva ejecución tras actualizar el proyecto.
6. La explicación de las diferencias entre GitHub, GitHub Actions y GitHub Pages.