Plugin Vite

Il plugin Vite viene fornito con il pacchetto unocss.

Installazione

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

npm

npm install -D unocss

bun

bun add -D unocss

Installa il plugin:

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

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

Crea un file uno.config.ts:

import { defineConfig } from 'unocss'

export default defineConfig({
  // ...opzioni UnoCSS
})

Aggiungi virtual:uno.css al tuo punto di ingresso principale:

import 'virtual:uno.css'

Modalità

Il plugin Vite viene fornito con una serie di modalità che abilitano comportamenti diversi.

global (predefinito)

Questa è la modalità predefinita per il plugin: in questa modalità devi aggiungere l'import di uno.css nel tuo punto di ingresso.

Questa modalità abilita una serie di plugin Vite per build e per dev con supporto HMR.

Il css generato sarà un foglio di stile globale iniettato nell'index.html.

vue-scoped

Questa modalità inietterà il CSS generato nei Vue SFCs <style scoped> per l'isolamento.

svelte-scoped

La modalità svelte-scoped è stata spostata nel suo pacchetto, vedi @unocss/svelte-scoped/vite.

shadow-dom

Poiché i Web Components usano Shadow DOM, non c'è modo di stilizzare il contenuto direttamente da un foglio di stile globale (a meno che non usi CSS custom properties, quelle penetreranno il Shadow DOM), devi iniettare inline il CSS generato dal plugin nello stile Shadow DOM.

Per iniettare inline il CSS generato, devi solo configurare la modalità del plugin su shadow-dom e includere il placeholder magico @unocss-placeholder in ogni blocco CSS di stile del componente web. Se stai definendo i tuoi Web Components in Vue SFCs e vuoi definire stili personalizzati insieme a UnoCSS, puoi avvolgere il placeholder in un commento CSS per evitare errori di sintassi nel tuo IDE.

per-module (sperimentale)

Questa modalità genererà un foglio CSS per ogni modulo, può essere scoped.

dist-chunk (sperimentale)

Questa modalità genererà un foglio CSS per ogni chunk di codice al build, ottimo per MPA.

Modificare le classi in DevTools

A causa della limitazione di "on-demand" dove i DevTools non conoscono quelle che non hai ancora usato nel tuo codice sorgente. Quindi se vuoi provare come funzionano le cose cambiando direttamente le classi nei DevTools, aggiungi semplicemente le seguenti righe al tuo punto di ingresso principale.

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

WARNING

Usalo con cautela, sotto il cofano usiamo MutationObserver per rilevare le modifiche alle classi. Il che significa che non solo le tue modifiche manuali ma anche le modifiche fatte dai tuoi script verranno rilevate e incluse nel foglio di stile. Questo potrebbe causare alcuni disallineamenti tra dev e il build di produzione quando aggiungi classi dinamiche basate su una logica nei tag script. Ti consigliamo di aggiungere le tue parti dinamiche alla safelist o impostare test di regressione UI per il tuo build di produzione se possibile.

Framework

Alcuni framework UI/App hanno alcune limitazioni che devono essere risolte per farlo funzionare, se stai usando uno dei seguenti framework, applica semplicemente i suggerimenti.

VanillaJS / TypeScript

Quando usi VanillaJS o TypeScript, devi aggiungere le estensioni dei file js e ts per permettere a UnoCSS di leggere e analizzare il contenuto, per impostazione predefinita i file js e ts sono esclusi, controlla la sezione Estrazione dalla Pipeline degli Strumenti di Build.

React

Se stai usando @vitejs/plugin-react:

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

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

Se stai usando @unocss/preset-attributify dovresti rimuovere tsc dallo script build.

Se stai usando @vitejs/plugin-react con @unocss/preset-attributify, devi aggiungere il plugin prima di @vitejs/plugin-react.

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

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

Puoi trovare un progetto di esempio React che usa entrambi i plugin nella directory examples/vite-react, controlla gli script in package.json e il file di configurazione Vite.

Preact

Se usi @preact/preset-vite:

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

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

Oppure se usi @prefresh/vite:

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

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

Se usi @unocss/preset-attributify, dovresti rimuovere tsc dallo script build.

Puoi trovare un progetto di esempio Preact che usa entrambi i plugin nella directory examples/vite-preact, controlla gli script in package.json e il file di configurazione Vite.

Svelte

Il plugin deve essere aggiunto prima di @sveltejs/vite-plugin-svelte.

Per supportare class:foo e class:foo={bar}, aggiungi il plugin e configura extractorSvelte nell'opzione extractors.

Puoi usare regole semplici per class: come class:bg-red-500={foo} o usare shortcuts contenenti più regole, vedi src/App.svelte nel progetto di esempio linkato sotto.

// 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(),
      ],
      /* più opzioni */
    }),
    svelte(),
  ],
}

Sveltekit

Per supportare class:foo e class:foo={bar}, aggiungi il plugin e configura extractorSvelte nell'opzione extractors.

Puoi usare regole semplici per class: come class:bg-red-500={foo} o usare shortcuts contenenti più regole, vedi src/routes/+layout.svelte nel progetto di esempio linkato sotto.

// 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(),
      ],
      /* più opzioni */
    }),
    sveltekit(),
  ],
}

Web Components

Per lavorare con i web components devi abilitare la modalità shadow-dom sul plugin.

Non dimenticare di rimuovere l'import per uno.css poiché la modalità shadow-dom non lo esporrà e l'applicazione non funzionerà.

import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      /* più opzioni */
    }),
  ],
}

Su ogni web component aggiungi semplicemente @unocss-placeholder al suo blocco CSS di stile:

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

Se stai usando Lit:

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

Hai un progetto di esempio Web Components nella directory examples/vite-lit.

Supporto integrato ::part

Puoi usare ::part poiché il plugin lo supporta tramite shortcuts e usando la regola part-[<part-name>]:<rule|shortcut> da preset-mini, ad esempio usandolo con regole semplici come part-[<part-name>]:bg-green-500 o usando qualche shortcut: controlla src/my-element.ts nel progetto di esempio linkato sotto.

La regola part-[<part-name>]:<rule|shortcut> funzionerà solo con questo plugin usando la modalità shadow-dom.

Il plugin usa nth-of-type per evitare collisioni con più parti nello stesso web component e per le stesse parti su web component distinti, non devi preoccupartene, il plugin se ne occuperà per te.

// 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' },
      ],
      /* più opzioni */
    }),
  ],
}

poi nei tuoi 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

Devi aggiungere il plugin vite-plugin-solid dopo il plugin di UnoCSS.

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

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

Puoi trovare un progetto di esempio Solid nella directory examples/vite-solid.

Elm

Devi aggiungere il plugin vite-plugin-elm prima del plugin di 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(),
  ],
})

Puoi trovare un progetto di esempio Elm nella directory examples/vite-elm.

Esempi

Esempio Base

Puoi trovare un progetto di esempio Vite base nella directory examples/vite-basic.

Esempi Framework

Forniamo progetti di esempio per diversi framework:

• Esempio Vite React
• Esempio Vite Preact
• Esempio Vite Svelte
• Esempio Vite Vue

Performance