Plugin de Vite

El plugin de Vite viene incluido en el paquete unocss.

Instalación

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

npm

npm install -D unocss

bun

bun add -D unocss

Instala el plugin:

import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UnoCSS(),
  ],
})

Crea un archivo uno.config.ts:

import { defineConfig } from 'unocss'

export default defineConfig({
  // ...opciones de UnoCSS
})

Añade virtual:uno.css a tu entrada principal:

import 'virtual:uno.css'

Modos

El plugin de Vite viene con un conjunto de modos que habilitan diferentes comportamientos.

global (predeterminado)

Este es el modo predeterminado para el plugin: en este modo necesitas añadir la importación de uno.css en tu punto de entrada.

Este modo habilita un conjunto de plugins de Vite para build y para dev con soporte de HMR.

El css generado será una hoja de estilos global inyectada en el index.html.

vue-scoped

Este modo inyectará el CSS generado a los <style scoped> de los SFCs de Vue para aislamiento.

svelte-scoped

El modo svelte-scoped se ha movido a su propio paquete, consulta @unocss/svelte-scoped/vite.

shadow-dom

Dado que los Web Components usan Shadow DOM, no hay forma de estilizar el contenido directamente desde una hoja de estilos global (a menos que uses CSS custom properties, esas penetrarán el Shadow DOM), necesitas insertar el CSS generado por el plugin en el estilo del Shadow DOM.

Para insertar el CSS generado, solo necesitas configurar el modo del plugin a shadow-dom e incluir el marcador de posición mágico @unocss-placeholder en cada bloque de CSS de estilo del componente web. Si estás definiendo tus Web Components en SFCs de Vue y quieres definir estilos personalizados junto con UnoCSS, puedes envolver el marcador de posición en un comentario CSS para evitar errores de sintaxis en tu IDE.

per-module (experimental)

Este modo generará una hoja de CSS para cada módulo, puede ser con alcance.

dist-chunk (experimental)

Este modo generará una hoja de CSS para cada fragmento de código en build, excelente para MPA.

Editar clases en DevTools

Debido a la limitación de "bajo demanda" donde las DevTools no conocen aquellas que aún no has usado en tu código fuente. Entonces, si quieres probar cómo funcionan las cosas cambiando directamente las clases en DevTools, solo añade las siguientes líneas a tu entrada principal.

import 'uno.css'
import 'virtual:unocss-devtools'

WARNING

Por favor úsalo con precaución, bajo el capó usamos MutationObserver para detectar los cambios de clase. Lo que significa que no solo tus cambios manuales sino también los cambios realizados por tus scripts serán detectados e incluidos en la hoja de estilos. Esto podría causar alguna desalineación entre dev y el build de producción cuando añadas clases dinámicas basadas en alguna lógica en etiquetas de script. Recomendamos añadir tus partes dinámicas a la safelist o configurar pruebas de regresión de UI para tu build de producción si es posible.

Frameworks

Algunos frameworks de UI/App tienen algunas advertencias que deben ser corregidas para que funcione, si estás usando uno de los siguientes frameworks, solo aplica las sugerencias.

VanillaJS / TypeScript

Cuando uses VanillaJS o TypeScript, necesitas añadir las extensiones de archivos js y ts para permitir que UnoCSS lea y analice el contenido, por defecto los archivos js y ts están excluidos, consulta la sección Extracción desde Pipeline de Herramientas de Build.

React

Si estás usando @vitejs/plugin-react:

import React from '@vitejs/plugin-react'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    React(),
    UnoCSS(),
  ],
}

Si estás usando @unocss/preset-attributify deberías remover tsc del script de build.

Si estás usando @vitejs/plugin-react con @unocss/preset-attributify, debes añadir el plugin antes de @vitejs/plugin-react.

import React from '@vitejs/plugin-react'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    React(),
  ],
}

Puedes encontrar un proyecto de ejemplo de React usando ambos plugins en el directorio examples/vite-react, consulta los scripts en package.json y el archivo de configuración de Vite.

Preact

Si usas @preact/preset-vite:

// vite.config.js
import Preact from '@preact/preset-vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Preact(),
  ],
}

O si usas @prefresh/vite:

// vite.config.js
import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS(),
    Prefresh(),
  ],
}

Si usas @unocss/preset-attributify, deberías remover tsc del script de build.

Puedes encontrar un proyecto de ejemplo de Preact usando ambos plugins en el directorio examples/vite-preact, consulta los scripts en package.json y el archivo de configuración de Vite.

Svelte

El plugin debe ser añadido antes de @sveltejs/vite-plugin-svelte.

Para soportar class:foo y class:foo={bar}, añade el plugin y configura extractorSvelte en la opción extractors.

Puedes usar reglas simples para class: como class:bg-red-500={foo} o usar shortcuts que contengan múltiples reglas, consulta src/App.svelte en el proyecto de ejemplo enlazado abajo.

// vite.config.js
import { svelte } from '@sveltejs/vite-plugin-svelte'
import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* más opciones */
    }),
    svelte(),
  ],
}

Sveltekit

Para soportar class:foo y class:foo={bar}, añade el plugin y configura extractorSvelte en la opción extractors.

Puedes usar reglas simples para class: como class:bg-red-500={foo} o usar shortcuts que contengan múltiples reglas, consulta src/routes/+layout.svelte en el proyecto de ejemplo enlazado abajo.

// vite.config.js
import { sveltekit } from '@sveltejs/kit/vite'
import extractorSvelte from '@unocss/extractor-svelte'
import UnoCSS from 'unocss/vite'

/** @type {import('vite').UserConfig} */
const config = {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* más opciones */
    }),
    sveltekit(),
  ],
}

Web Components

Para trabajar con web components necesitas habilitar el modo shadow-dom en el plugin.

No olvides remover la importación de uno.css ya que el modo shadow-dom no la expondrá y la aplicación no funcionará.

import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      /* más opciones */
    }),
  ],
}

En cada web component solo añade @unocss-placeholder a su bloque de CSS de estilo:

const template = document.createElement('template')
template.innerHTML = `
<style>
:host {...}
@unocss-placeholder
</style>
<div class="m-1em">
...
</div>
`

Si estás usando Lit:

@customElement('my-element')
export class MyElement extends LitElement {
  static styles = css`
    :host {...}
    @unocss-placeholder
  `
  // ...
}

Tienes un proyecto de ejemplo de Web Components en el directorio examples/vite-lit.

Soporte integrado para ::part

Puedes usar ::part ya que el plugin lo soporta a través de shortcuts y usando la regla part-[<part-name>]:<rule|shortcut> de preset-mini, por ejemplo usándolo con reglas simples como part-[<part-name>]:bg-green-500 o usando algún shortcut: consulta src/my-element.ts en el proyecto de ejemplo enlazado abajo.

La regla part-[<part-name>]:<rule|shortcut> solo funcionará con este plugin usando el modo shadow-dom.

El plugin usa nth-of-type para evitar colisiones con múltiples partes en el mismo web component y para las mismas partes en web components distintos, no necesitas preocuparte por ello, el plugin se encargará por ti.

// vite.config.js
import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      shortcuts: [
        { 'cool-blue': 'bg-blue-500 text-white' },
        { 'cool-green': 'bg-green-500 text-black' },
      ],
      /* más opciones */
    }),
  ],
}

entonces en tus web components:

// my-container-wc.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<my-wc-with-parts class="part-[cool-part]:cool-blue part-[another-cool-part]:cool-green">...</my-wc-with-parts>
`

// my-wc-with-parts.ts
const template = document.createElement('template')
template.innerHTML = `
<style>
@unocss-placeholder
</style>
<div>
  <div part="cool-part">...</div>
  <div part="another-cool-part">...</div>
</div>
`

Solid

Necesitas añadir el plugin vite-plugin-solid después del plugin de UnoCSS.

// vite.config.js
import UnoCSS from 'unocss/vite'
import solidPlugin from 'vite-plugin-solid'

export default {
  plugins: [
    UnoCSS({
      /* opciones */
    }),
    solidPlugin(),
  ],
}

Puedes encontrar un proyecto de ejemplo de Solid en el directorio examples/vite-solid.

Elm

Necesitas añadir el plugin vite-plugin-elm antes del plugin de UnoCSS.

// vite.config.js
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'
import Elm from 'vite-plugin-elm'

export default defineConfig({
  plugins: [
    Elm(),
    UnoCSS(),
  ],
})

Puedes encontrar un proyecto de ejemplo de Elm en el directorio examples/vite-elm.

Ejemplos

Ejemplo Básico

Puedes encontrar un proyecto de ejemplo básico de Vite en el directorio examples/vite-basic.

Ejemplos de Frameworks

Proporcionamos proyectos de ejemplo para diferentes frameworks:

• Ejemplo de Vite React
• Ejemplo de Vite Preact
• Ejemplo de Vite Svelte
• Ejemplo de Vite Vue

Rendimiento