Extracción

UnoCSS funciona buscando los usos de utilidades de tu código base y generando el CSS correspondiente bajo demanda. Llamamos a este proceso extracción.

Fuentes de Contenido

UnoCSS soporta extraer usos de utilidades de múltiples fuentes:

• Pipeline - Extraer directamente desde la tubería de tus herramientas de construcción
• Sistema de archivos - Extraer desde tu sistema de archivos leyendo y observando archivos
• En línea - Extraer desde texto plano en línea

Los usos de utilidades que provienen de diferentes fuentes se fusionarán juntos y generarán el CSS final.

Extrayendo desde la Tubería de Herramientas de Construcción

Esto está soportado en las integraciones de Vite y Webpack.

UnoCSS leerá el contenido que pasa por la tubería de tus herramientas de construcción y extraerá los usos de utilidades de ellos. Esta es la forma más eficiente y precisa de extraer ya que solo extraemos los usos que realmente se usan en tu aplicación de manera inteligente sin que se haga I/O de archivos adicional durante la extracción.

Por defecto, UnoCSS extraerá el uso de utilidades de archivos en tu tubería de construcción con extensión .jsx, .tsx, .vue, .md, .html, .svelte, .astro y luego generará el CSS apropiado bajo demanda. Los archivos .js y .ts NO están incluidos por defecto.

Para configurarlos, puedes actualizar tu uno.config.ts:

export default defineConfig({
  content: {
    pipeline: {
      include: [
        // el por defecto
        /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
        // incluir archivos js/ts
        'src/**/*.{js,ts}',
      ],
      // excluir archivos
      // exclude: []
    },
  },
})

También puedes agregar el comentario mágico @unocss-include, por archivo, en cualquier lugar del archivo que quieras que UnoCSS escanee. Si necesitas escanear archivos *.js o *.ts, agrégalos en la configuración para incluir todos los archivos js/ts como objetivos de escaneo.

// ./some-utils.js

// ya que los archivos `.js` no están incluidos por defecto,
// el siguiente comentario le dice a UnoCSS que fuerce el escaneo de este archivo.
// @unocss-include
export const classes = {
  active: 'bg-primary text-white',
  inactive: 'bg-gray-200 text-gray-500',
}

De manera similar, también puedes agregar @unocss-ignore para omitir el escaneo y transformación para todo el archivo.

Si quieres que UnoCSS omita un bloque de código sin ser extraído en ningún archivo de extracción, puedes usar @unocss-skip-start @unocss-skip-end en pares. Ten en cuenta que debe usarse en pares para ser efectivo.

<p class="text-green text-xl">Verde Grande</p>

<!-- @unocss-skip-start -->
<!-- `text-red` no será extraído -->
<p class="text-red">Rojo</p>
<!-- @unocss-skip-end -->

Extrayendo desde el Sistema de Archivos

En casos donde estés usando integraciones que no tienen acceso a la tubería de herramientas de construcción (por ejemplo, el plugin PostCSS), o estés integrando con frameworks de backend de tal manera que el código no pase por la tubería, puedes especificar manualmente los archivos a extraer.

export default defineConfig({
  content: {
    filesystem: [
      'src/**/*.php',
      'public/*.html',
    ],
  },
})

Los archivos coincidentes serán leídos directamente desde el sistema de archivos y observados para cambios en modo dev.

Extrayendo desde Texto En Línea

Además, también puedes extraer usos de utilidades desde texto en línea, que podrías obtener de otro lugar.

También puedes pasar una función asíncrona para devolver el contenido. Pero ten en cuenta que la función solo se llamará una vez en el momento de la construcción.

export default defineConfig({
  content: {
    inline: [
      // texto plano
      '<div class="p-4 text-red">Algún texto</div>',
      // getter asíncrono
      async () => {
        const response = await fetch('https://example.com')
        return response.text()
      },
    ],
  },
})

Limitaciones

Como UnoCSS funciona en tiempo de construcción, significa que solo las utilidades presentadas estáticamente serán generadas y enviadas a tu aplicación. Las utilidades que se usan dinámicamente o se obtienen de recursos externos en tiempo de ejecución podrían NO ser detectadas o aplicadas.

Lista de Seguridad

A veces podrías querer usar concatenaciones dinámicas como:

<div class="p-${size}"></div>
<!-- ¡esto no funcionará! -->

Debido al hecho de que UnoCSS funciona en tiempo de construcción usando extracción estática, en el momento de la compilación no puede saber todas las combinaciones de las utilidades entonces. Para eso, puedes configurar la opción safelist.

safelist: 'p-1 p-2 p-3 p-4'.split(' ')

El CSS correspondiente siempre será generado:

.p-1 { padding: 0.25rem; }
.p-2 { padding: 0.5rem; }
.p-3 { padding: 0.75rem; }
.p-4 { padding: 1rem; }

O más flexible:

safelist: [
  ...Array.from({ length: 4 }, (_, i) => `p-${i + 1}`),
]

Si estás buscando una generación verdaderamente dinámica en tiempo de ejecución, podrías querer revisar el paquete @unocss/runtime.

Combinaciones de Lista Estática

Otra forma de trabajar alrededor de la limitación de utilidades construidas dinámicamente es que puedes usar un objeto que liste todas las combinaciones estáticamente. Por ejemplo, si quieres tener esto:

<div class="text-${color} border-${color}"></div>
<!-- ¡esto no funcionará! -->

Puedes crear un objeto que liste todas las combinaciones (asumiendo que conoces cualquier valor posible de color que quieras usar)

// Como son estáticos, UnoCSS podrá extraerlos en tiempo de construcción
const classes = {
  red: 'text-red border-red',
  green: 'text-green border-green',
  blue: 'text-blue border-blue',
}

Y luego usarlo en tu plantilla:

<div class="${classes[color]}"></div>

Lista de Bloqueo

Similar a safelist, también puedes configurar blocklist para excluir algunas utilidades de ser generadas. Esto es útil para excluir algunos falsos positivos de extracción. Diferente de safelist, blocklist acepta tanto cadenas para coincidencia exacta como expresiones regulares para coincidencia de patrón.

blocklist: [
  'p-1',
  /^p-[2-4]$/,
]

Esto excluirá p-1 y p-2, p-3, p-4 de ser generados.