Plugin Vite

Le plugin Vite est fourni avec le package unocss.

Installation

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

npm

npm install -D unocss

bun

bun add -D unocss

Installez le plugin :

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

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

Créez un fichier uno.config.ts :

import { defineConfig } from 'unocss'

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

Ajoutez virtual:uno.css à votre point d'entrée principal :

import 'virtual:uno.css'

Modes

Le plugin Vite propose plusieurs modes qui activent différents comportements.

global (par défaut)

C'est le mode par défaut du plugin : dans ce mode, vous devez importer uno.css dans votre point d'entrée.

Ce mode active un ensemble de plugins Vite pour la build et pour le dev avec support HMR.

Le css généré sera une feuille de style globale injectée dans le index.html.

vue-scoped

Ce mode injecte le CSS généré dans les <style scoped> des SFC Vue pour l'isolation.

svelte-scoped

Le mode svelte-scoped a été déplacé dans son propre package, voir @unocss/svelte-scoped/vite.

shadow-dom

Comme les Web Components utilisent le Shadow DOM, il n'est pas possible de styliser le contenu directement depuis une feuille de style globale (sauf si vous utilisez des CSS custom properties, qui pénètrent le Shadow DOM). Vous devez inclure le CSS généré par le plugin dans le style du Shadow DOM.

Pour inclure le CSS généré, il suffit de configurer le mode du plugin sur shadow-dom et d'inclure le placeholder magique @unocss-placeholder dans chaque bloc CSS de style de composant web. Si vous définissez vos Web Components dans des SFC Vue et souhaitez définir des styles personnalisés avec UnoCSS, vous pouvez entourer le placeholder d'un commentaire CSS pour éviter les erreurs de syntaxe dans votre IDE.

per-module (expérimental)

Ce mode génère une feuille CSS pour chaque module, peut être scoped.

dist-chunk (expérimental)

Ce mode génère une feuille CSS pour chaque chunk de code lors de la build, idéal pour les MPA.

Modifier les classes dans DevTools

En raison de la limitation du mode "on-demand" où les DevTools ne connaissent pas les classes que vous n'avez pas encore utilisées dans votre code source, si vous souhaitez tester en modifiant directement les classes dans DevTools, ajoutez simplement les lignes suivantes à votre point d'entrée principal.

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

WARNING

À utiliser avec précaution : en interne, nous utilisons MutationObserver pour détecter les changements de classe. Cela signifie que non seulement vos modifications manuelles mais aussi celles faites par vos scripts seront détectées et incluses dans la feuille de style. Cela peut entraîner des différences entre le développement et la build de production si vous ajoutez des classes dynamiques via des scripts. Nous recommandons d'ajouter vos parties dynamiques à la safelist ou de mettre en place des tests de régression UI pour votre build de production si possible.

Frameworks

Certains frameworks UI/App nécessitent des ajustements pour fonctionner correctement. Si vous utilisez l'un des frameworks suivants, appliquez simplement les suggestions.

VanillaJS / TypeScript

Lorsque vous utilisez VanillaJS ou TypeScript, vous devez ajouter les extensions de fichiers js et ts pour permettre à UnoCSS de lire et d'analyser le contenu. Par défaut, les fichiers js et ts sont exclus, consultez la section Extraction depuis la pipeline des outils de build.

React

Si vous utilisez @vitejs/plugin-react :

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

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

Si vous utilisez @unocss/preset-attributify, vous devez retirer tsc du script build.

Si vous utilisez @vitejs/plugin-react avec @unocss/preset-attributify, vous devez ajouter le plugin avant @vitejs/plugin-react.

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

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

Vous pouvez trouver un projet exemple React utilisant les deux plugins dans le dossier examples/vite-react, consultez les scripts dans package.json et le fichier de config Vite.

Preact

Si vous utilisez @preact/preset-vite :

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

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

Ou si vous utilisez @prefresh/vite :

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

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

Si vous utilisez @unocss/preset-attributify, vous devez retirer tsc du script build.

Vous pouvez trouver un projet exemple Preact utilisant les deux plugins dans le dossier examples/vite-preact, consultez les scripts dans package.json et le fichier de config Vite.

Svelte

Le plugin doit être ajouté avant @sveltejs/vite-plugin-svelte.

Pour supporter class:foo et class:foo={bar}, ajoutez le plugin et configurez extractorSvelte dans l'option extractors.

Vous pouvez utiliser des règles simples pour class: comme class:bg-red-500={foo} ou utiliser des shortcuts contenant plusieurs règles, voir src/App.svelte dans le projet exemple ci-dessous.

// 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(),
      ],
      /* plus d'options */
    }),
    svelte(),
  ],
}

Sveltekit

Pour supporter class:foo et class:foo={bar}, ajoutez le plugin et configurez extractorSvelte dans l'option extractors.

Vous pouvez utiliser des règles simples pour class: comme class:bg-red-500={foo} ou utiliser des shortcuts contenant plusieurs règles, voir src/routes/+layout.svelte dans le projet exemple ci-dessous.

// 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(),
      ],
      /* plus d'options */
    }),
    sveltekit(),
  ],
}

Web Components

Pour utiliser UnoCSS avec les web components, vous devez activer le mode shadow-dom sur le plugin.

N'oubliez pas de retirer l'import de uno.css car le mode shadow-dom ne l'exposera pas et l'application ne fonctionnera pas.

import UnoCSS from 'unocss/vite'

export default {
  plugins: [
    UnoCSS({
      mode: 'shadow-dom',
      /* plus d'options */
    }),
  ],
}

Dans chaque web component, ajoutez simplement @unocss-placeholder dans le bloc CSS du style :

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

Si vous utilisez Lit :

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

Vous trouverez un projet exemple Web Components dans le dossier examples/vite-lit.

Support intégré de ::part

Vous pouvez utiliser ::part car le plugin le prend en charge via les shortcuts et la règle part-[<part-name>]:<rule|shortcut> du preset-mini, par exemple en l'utilisant avec des règles simples comme part-[<part-name>]:bg-green-500 ou avec un shortcut : voir src/my-element.ts dans le projet exemple ci-dessous.

La règle part-[<part-name>]:<rule|shortcut> ne fonctionne qu'avec ce plugin en mode shadow-dom.

Le plugin utilise nth-of-type pour éviter les collisions avec plusieurs parts dans le même web component et pour les mêmes parts sur différents web components, vous n'avez pas à vous en soucier, le plugin s'en charge pour vous.

// 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' },
      ],
      /* plus d'options */
    }),
  ],
}

puis dans vos 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

Vous devez ajouter le plugin vite-plugin-solid après le plugin UnoCSS.

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

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

Vous trouverez un projet exemple Solid dans le dossier examples/vite-solid.

Elm

Vous devez ajouter le plugin vite-plugin-elm avant le plugin 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(),
  ],
})

Vous trouverez un projet exemple Elm dans le dossier examples/vite-elm.

Exemples

Exemple de base

Vous trouverez un projet exemple Vite de base dans le dossier examples/vite-basic.

Exemples de frameworks

Nous fournissons des projets exemples pour différents frameworks :

• Exemple Vite React
• Exemple Vite Preact
• Exemple Vite Svelte
• Exemple Vite Vue

Performance