Plugin de Inyecci贸n HTML para Vite

January 30, 2025 路 View on GitHub

NPM NPM downloads

馃嚞馃嚙 English | 馃嚜馃嚫 Espa帽ol | 馃嚪馃嚭 袪褍褋褋泻懈泄 | 馃嚚馃嚦 涓枃

Plugin de Vite para inyectar fragmentos de c贸digo HTML, JS y CSS en index.html.

Prop贸sito

A menudo, al desarrollar aplicaciones front-end, es necesario integrar diversas bibliotecas en el archivo index.html. Por ejemplo, puede que quieras incluir c贸digo para Google Analytics, service workers de PWA, metadatos de Open Graph y Twitter Card, pantallas de bienvenida, widgets de soporte al cliente y mucho m谩s.

Como resultado, index.html se vuelve sobrecargado y dif铆cil de gestionar.

Este plugin te permite almacenar fragmentos de c贸digo en archivos separados, manteniendo index.html limpio y ordenado, e inyect谩ndolos en tiempo de compilaci贸n. No es necesario utilizar etiquetas de marcador de posici贸n especiales en el index.html.

El plugin tambi茅n soporta Vite dev server HMR, lo que significa que puedes editar los fragmentos de c贸digo y ver los resultados inmediatamente en el navegador.

Adem谩s, el plugin permite configuraciones diferentes en los modos de desarrollo y producci贸n. Al especificar la propiedad buildModes, puedes habilitar o deshabilitar fragmentos espec铆ficos dependiendo del entorno, simplificando el desarrollo y reduciendo el c贸digo innecesario en las compilaciones de producci贸n.

Descripci贸n

Existen tres tipos de fragmentos de c贸digo: raw, js y css. Los fragmentos raw se inyectan tal cual, mientras que los fragmentos js y css se envuelven en etiquetas <script> y <style> respectivamente. El valor predeterminado para type es raw.

Hay cuatro lugares donde puedes inyectar un fragmento de c贸digo en el index.html:

  • Al inicio de la etiqueta <head> (head-prepend)
  • Al final de la etiqueta <head> (head)
  • Al inicio de la etiqueta <body> (body-prepend)
  • Al final de la etiqueta <body> (body)

Los valores correspondientes para injectTo son: head-prepend, head, body-prepend y body.


Instalaci贸n

pnpm add vite-plugin-html-injection -D

yarn add vite-plugin-html-injection -D

npm i vite-plugin-html-injection -D

Uso

  1. A帽ade vite-plugin-html-injection a tus plugins de Vite con la configuraci贸n requerida:
// vite.config.js

import { defineConfig } from "vite";
import { htmlInjectionPlugin } from "vite-plugin-html-injection";

export default defineConfig({
  plugins: [
    htmlInjectionPlugin({
      // orden de transformaci贸n - establece en "pre" para usar reemplazo de variables de entorno en archivos HTML
      // Ver https://vite.dev/guide/api-plugin.html#transformindexhtml
      order: "pre",
      // inyecciones de ejemplo
      injections: [
        {
          // (opcional) nombre de la inyecci贸n
          name: "Open Graph",
          // ruta al archivo del fragmento de c贸digo relativo a la ra铆z del proyecto Vite
          path: "./src/injections/open-graph.html",
          // (opcional) tipo de fragmento de c贸digo: raw | js | css
          type: "raw",
          // d贸nde inyectar: head | body | head-prepend | body-prepend
          injectTo: "head",
          // (opcional) modos a los que se aplica: dev | prod | both
          buildModes: "both",
        },
        {
          name: "Google Analytics",
          path: "./src/injections/ga.html",
          type: "raw",
          injectTo: "body",
          buildModes: "prod",
        },
      ],
    }),
  ],
});

Sugerencia:

Puedes colocar el objeto de configuraci贸n en un archivo JSON separado e importarlo en el vite.config.js.


  1. Crea los fragmentos de c贸digo correspondientes:

<!-- ./src/injections/open-graph.html -->

<!-- Meta Tags de Facebook -->
<meta property="og:url" content="https://www.acme.com/" />
<meta property="og:type" content="website" />
<meta property="og:title" content="Mi sitio web de Acme" />
<meta property="og:description" content="Bienvenido a mi sitio web de Acme" />
<meta property="og:image" content="https://www.acme.com/logo.png" />


<!-- ./src/injections/ga.html -->

<!-- Etiqueta de Google (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-8W4X32XXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() {
    dataLayer.push(arguments);
  }
  gtag("js", new Date());

  gtag("config", "G-8W4X32XXXX");
</script>

Eso es todo. Despu茅s de ejecutar el comando npm serve o npm build, los fragmentos de c贸digo ser谩n inyectados.


Configuraci贸n para Diferentes Modos

El plugin soporta configuraciones diferentes para los entornos de desarrollo y producci贸n. Al configurar la propiedad buildModes para cada inyecci贸n, puedes controlar si un fragmento se incluye en el servidor de desarrollo, en la compilaci贸n de producci贸n o en ambos. Esta flexibilidad te permite deshabilitar fragmentos de c贸digo innecesarios durante el desarrollo, mejorando el rendimiento y simplificando el proceso de desarrollo.

export interface IHtmlInjectionConfig {
  injections: IHtmlInjectionConfigInjection[];
  order?: "pre" | "post";
}

export interface IHtmlInjectionConfigInjection {
  name?: string;
  path: string;
  type?: "raw" | "js" | "css"; // valor por defecto es 'raw'
  injectTo: "head" | "body" | "head-prepend" | "body-prepend";
  buildModes?: "dev" | "prod" | "both"; // valor por defecto es 'both'
}

Firma

El plugin est谩 altamente tipado. Aqu铆 est谩 la firma de su configuraci贸n:

export interface IHtmlInjectionConfig {
  injections: IHtmlInjectionConfigInjection[];
  order?: "pre" | "post";
}

export interface IHtmlInjectionConfigInjection {
  name?: string;
  path: string;
  type?: "raw" | "js" | "css"; // valor por defecto es 'raw'
  injectTo: "head" | "body" | "head-prepend" | "body-prepend";
  buildModes?: "dev" | "prod" | "both"; // valor por defecto es 'both'
}

Si Te Gusta, Estrella el Proyecto

隆Gracias!


Contribuciones

Eres bienvenido a hacer sugerencias a trav茅s de GitHub Issues o extender la funcionalidad al hacer un fork, modificar y crear un PR a este plugin para Vite.


Licencia

Licencia MIT 漏 2023-2024


Traducciones Disponibles