Viteプラグイン

Viteプラグインはunocssパッケージに同梱されています。

インストール

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

npm

npm install -D unocss

bun

bun add -D unocss

プラグインをインストールします：

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

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

uno.config.tsファイルを作成します：

import { defineConfig } from 'unocss'

export default defineConfig({
  // ...UnoCSSのオプション
})

メインエントリにvirtual:uno.cssを追加します：

import 'virtual:uno.css'

モード

Viteプラグインには、さまざまな動作を有効にするモードが用意されています。

global（デフォルト）

これはプラグインのデフォルトモードです：このモードではエントリーポイントでuno.cssのインポートが必要です。

このモードでは、build用とdev用にHMRサポート付きのViteプラグインが有効になります。

生成されたCSSはindex.htmlにグローバルスタイルシートとして注入されます。

vue-scoped

このモードでは、生成されたCSSがVue SFCの<style scoped>に注入され、分離されます。

svelte-scoped

svelte-scopedモードは独自のパッケージに移動されました。@unocss/svelte-scoped/viteを参照してください。

shadow-dom

Web ComponentsはShadow DOMを使用するため、グローバルスタイルシートから直接コンテンツをスタイルすることはできません（CSSカスタムプロパティを使う場合を除く）。プラグインで生成されたCSSをShadow DOMのスタイルにインライン化する必要があります。

生成されたCSSをインライン化するには、プラグインのモードをshadow-domに設定し、各WebコンポーネントのCSSブロックに@unocss-placeholderマジックプレースホルダーを含めるだけです。Vue SFCでWeb Componentsを定義し、UnoCSSとカスタムスタイルを併用したい場合は、IDEの構文エラーを避けるためにプレースホルダーをCSSコメントでラップできます。

per-module（実験的）

このモードでは、各モジュールごとにCSSシートが生成され、スコープ化も可能です。

dist-chunk（実験的）

このモードでは、ビルド時に各コードチャンクごとにCSSシートが生成され、MPAに最適です。

DevToolsでクラスを編集

オンデマンド方式の制限により、DevToolsはまだソースコードで使用していないクラスを認識できません。そのため、DevToolsで直接クラスを変更して動作を試したい場合は、メインエントリに以下を追加してください。

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

WARNING

ご注意ください。内部的にはMutationObserverを使ってクラスの変更を検出しています。つまり、手動の変更だけでなくスクリプトによる変更も検出され、スタイルシートに含まれます。スクリプトタグ内のロジックで動的にクラスを追加した場合、開発と本番ビルドでズレが生じる可能性があります。可能であれば、動的部分はsafelistに追加するか、本番ビルド用のUIリグレッションテストを設定することを推奨します。

フレームワーク

一部のUI/Appフレームワークでは、動作させるために修正が必要な場合があります。以下のフレームワークを使用している場合は、提案に従ってください。

VanillaJS / TypeScript

VanillaJSやTypeScriptを使用する場合、jsやtsファイル拡張子を追加してUnoCSSが内容を読み取れるようにする必要があります。デフォルトではjsとtsファイルは除外されています。ビルドツールパイプラインからの抽出セクションを参照してください。

React

@vitejs/plugin-reactを使用している場合：

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

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

@unocss/preset-attributifyを使用している場合は、buildスクリプトからtscを削除してください。

@vitejs/plugin-reactと@unocss/preset-attributifyを併用する場合は、UnoCSSのプラグインを@vitejs/plugin-reactより前に追加してください。

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

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

examples/vite-reactディレクトリに両方のプラグインを使ったReactのサンプルプロジェクトがあります。package.jsonのスクリプトやVite設定ファイルを確認してください。

Preact

@preact/preset-viteを使用している場合：

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

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

@prefresh/viteを使用している場合：

import Prefresh from '@prefresh/vite'
import UnoCSS from 'unocss/vite'

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

@unocss/preset-attributifyを使用している場合は、buildスクリプトからtscを削除してください。

examples/vite-preactディレクトリに両方のプラグインを使ったPreactのサンプルプロジェクトがあります。package.jsonのスクリプトやVite設定ファイルを確認してください。

Svelte

プラグインは@sveltejs/vite-plugin-svelteより前に追加する必要があります。

class:fooやclass:foo={bar}をサポートするには、プラグインを追加し、extractorsオプションでextractorSvelteを設定してください。

class:でシンプルなルールを使うことができます。例えばclass:bg-red-500={foo}や、shortcutsを使って複数のルールを含めることもできます。詳細は下記のサンプルプロジェクトのsrc/App.svelteを参照してください。

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

export default {
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    svelte(),
  ],
}

Sveltekit

class:fooやclass:foo={bar}をサポートするには、プラグインを追加し、extractorsオプションでextractorSvelteを設定してください。

class:でシンプルなルールを使うことができます。例えばclass:bg-red-500={foo}や、shortcutsを使って複数のルールを含めることもできます。詳細は下記のサンプルプロジェクトのsrc/routes/+layout.svelteを参照してください。

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

export default defineConfig({
  plugins: [
    UnoCSS({
      extractors: [
        extractorSvelte(),
      ],
      /* more options */
    }),
    sveltekit(),
  ],
})

Web Components

Web Componentsで動作させるには、プラグインのshadow-domモードを有効にする必要があります。

shadow-domモードではuno.cssのインポートを削除してください。これを残すとアプリケーションが正しく動作しません。

import UnoCSS from 'unocss/vite'

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

各WebコンポーネントのCSSブロックに@unocss-placeholderを追加します：

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

Litを使用している場合：

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

examples/vite-litディレクトリにWeb Componentsのサンプルプロジェクトがあります。

::partの組み込みサポート

このプラグインはshortcutsとpreset-miniのpart-[<part-name>]:<rule|shortcut>ルールを使って::partをサポートしています。例えばpart-[<part-name>]:bg-green-500やshortcutを使うことができます。詳細は下記のサンプルプロジェクトのsrc/my-element.tsを参照してください。

part-[<part-name>]:<rule|shortcut>はこのプラグインのshadow-domモードでのみ動作します。

このプラグインはnth-of-typeを使って、同じWebコンポーネント内の複数のpartや異なるWebコンポーネントの同じpart間の衝突を回避します。ユーザーは特に気にする必要はありません。

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

Webコンポーネント内で：

// 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

vite-plugin-solidプラグインはUnoCSSの後に追加する必要があります。

import UnoCSS from 'unocss/vite'
import solidPlugin from 'vite-plugin-solid'

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

Elm

vite-plugin-elmプラグインはUnoCSSの前に追加する必要があります。

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

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

レガシー

@vitejs/plugin-legacyでrenderModernChunks: falseを使う場合は、unocssオプションに追加する必要があります。

import legacy from '@vitejs/plugin-legacy'
import vue from '@vitejs/plugin-vue'
import { presetWind3 } from 'unocss'
import Unocss from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    vue(),
    Unocss({
      presets: [presetWind3()],
      legacy: {
        renderModernChunks: false,
      },
    }),
    legacy({
      targets: ['defaults', 'not IE 11'],
      renderModernChunks: false,
    }),
  ],
})

ライセンス

• MIT License © 2021-PRESENT Anthony Fu