Saltar al contenido

Personalizar nombres de archivos en la salida del build

Por defecto, el comando astro build saca tus assets compilados desde el código fuente de tu proyecto, como archivos JavaScript y CSS ubicados en el directorio src/, hacia un directorio _astro con nombres de archivo hasheados (ej. _astro/index.DRf8L97S.js) que son excelentes para caché a largo plazo.

Aunque normalmente no es necesario, puedes personalizar los nombres de archivo de salida cuando lo necesites. Por ejemplo, esto puede ser útil si tienes scripts con nombres que podrían activar bloqueadores de anuncios (ej. ads.js), o si quieres organizar tus assets con una convención de nombres particular. Al personalizar las opciones de salida de Rollup, puedes ganar más control sobre la estructura de build de tu proyecto, permitiéndote cumplir con requisitos específicos de organización o despliegue.

Receta

Sección titulada “Receta”

Esta receta configura vite.environments.client.build.rollupOptions para sacar los assets compilados con la siguiente estructura y patrón de nombres:

  • Archivos de entrada JavaScript (ej. scripts directamente asociados con tus páginas o layouts): dist/js/[name]-[hash].js
  • Chunks de code-splitting de JavaScript (ej. componentes importados dinámicamente o módulos compartidos): dist/js/chunks/[name]-[hash].js
  • Otros assets (ej. CSS, imágenes, fuentes): dist/static/[name]-[hash][extname] (ej. dist/static/styles-a1b2c3d4.css, dist/static/logo-e5f6g7h8.svg)

  1. Añadir opciones de salida de Rollup de Vite.

    Modifica tu astro.config.mjs para incluir la siguiente configuración de vite.environments.client.build.rollupOptions.output. Aquí es donde puedes definir los patrones de nombres personalizados para tus assets usando entryFileNames, chunkFileNames, y assetFileNames de Rollup:

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    

    export default defineConfig({
      // ...
      vite: {
        environments: {
          client: {
            build: {
              rollupOptions: {
                output: {
                  // path names relative to `outDir`
                  entryFileNames: 'js/[name]-[hash].js',
                  chunkFileNames: 'js/chunks/[name]-[hash].js',
                  assetFileNames: 'static/[name]-[hash][extname]',
                },
              },
            },
          },
        },
      },
    });

    Este ejemplo usa los siguientes placeholders de nombres de archivo:

    • [name]: El nombre original del archivo (sin la extensión ni la ruta).
    • [hash]: Un hash basado en el contenido generado para el archivo, crucial para cache busting. También puedes especificar una longitud, ej. [hash:8]. Esto asegura que cuando actualizas un asset, el nombre del archivo cambia, forzando a los navegadores a descargar la nueva versión en lugar de servir una versión cacheada obsoleta.
    • [extname]: La extensión original del archivo, incluyendo el punto inicial (ej. .js, .css, .svg).

    Para una lista completa de placeholders disponibles y patrones avanzados para estas opciones, consulta la documentación de configuración de Rollup.

  2. Compila tu proyecto.

    Dado que estas personalizaciones de nombres de archivo aplican solo a la salida del build de producción, necesitarás ejecutar el comando de build de tu proyecto:

    Ventana de la terminal
    npm run build

  3. Después de que el build se complete, inspecciona tu directorio de salida (dist/ por defecto).

    Verifica que los assets compilados de tu proyecto src estén nombrados y organizados según los nuevos patrones. (Los archivos de tu directorio public/ se copian directamente al directorio de salida y no se ven afectados por estas opciones de nombres de Rollup.)

    Dependiendo del contenido específico de tu proyecto, tu carpeta de build ahora se verá algo así:

    • Directoriodist/
      • Directoriojs/
        • index-a1b2c3d4.js
        • Directoriochunks/
          • common-e5f6g7h8.js
      • Directorioimg/
        • logo-i9j0k1l2.png
      • Directoriofonts/
        • myfont-q2w3e4r5.woff2
      • Directoriostatic_assets/
        • styles-m3n4o5p6.css
      • index.html
      • Directorioabout/
        • index.html
      • … (otros archivos HTML y assets públicos)
Contribuir Comunidad Patrocinar