Vite Plugin

Vite plugin มาพร้อมกับแพ็กเกจ unocss

การติดตั้ง

pnpm

pnpm add -D unocss

yarn

yarn add -D unocss

npm

npm install -D unocss

bun

bun add -D unocss

ติดตั้ง plugin:

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 options
})

เพิ่ม virtual:uno.css ไปยัง entry point หลักของคุณ:

import 'virtual:uno.css'

Modes

Vite plugin มาพร้อมกับชุดของ modes ที่เปิดใช้งานพฤติกรรมที่แตกต่างกัน

global (default)

นี่เป็น mode เริ่มต้นสำหรับ plugin: ใน mode นี้คุณต้องเพิ่ม import ของ uno.css ใน entry point ของคุณ

mode นี้เปิดใช้งานชุดของ Vite plugins สำหรับ build และสำหรับ dev พร้อมการรองรับ HMR

css ที่สร้างขึ้นจะเป็น global stylesheet ที่ถูก inject ลงใน index.html

vue-scoped

mode นี้จะ inject CSS ที่สร้างขึ้นไปยัง Vue SFCs <style scoped> เพื่อการแยกส่วน

svelte-scoped

svelte-scoped mode ถูกย้ายไปเป็นแพ็กเกจของตัวเองแล้ว ดูที่ @unocss/svelte-scoped/vite

shadow-dom

เนื่องจาก Web Components ใช้ Shadow DOM จึงไม่มีวิธีจัด style เนื้อหาโดยตรงจาก global stylesheet (เว้นแต่คุณใช้ CSS custom properties ซึ่งจะสามารถ穿透 Shadow DOM ได้) คุณต้อง inline CSS ที่สร้างขึ้นโดย plugin เข้าไปใน Shadow DOM style

เพื่อ inline CSS ที่สร้างขึ้น คุณเพียงแค่ต้องกำหนดค่า plugin mode เป็น shadow-dom และรวม @unocss-placeholder magic placeholder ในแต่ละ web component style CSS block หากคุณกำลังกำหนด Web Components ของคุณใน Vue SFCs และต้องการกำหนด custom styles พร้อมกับ UnoCSS คุณสามารถห่อ placeholder ใน CSS comment เพื่อหลีกเลี่ยง syntax errors ใน IDE ของคุณ

per-module (experimental)

mode นี้จะสร้าง CSS sheet สำหรับแต่ละ module สามารถกำหนด scope ได้

dist-chunk (experimental)

mode นี้จะสร้าง CSS sheet สำหรับแต่ละ code chunk เมื่อ build เหมาะสำหรับ MPA

แก้ไข classes ใน DevTools

เนื่องจากข้อจำกัดของ "on-demand" ที่ DevTools ไม่รู้จักสิ่งที่คุณยังไม่ได้ใช้ใน source code ของคุณ ดังนั้นหากคุณต้องการลองดูว่าสิ่งต่างๆ ทำงานอย่างไรโดยการเปลี่ยน classes โดยตรงใน DevTools เพียงเพิ่มบรรทัดต่อไปนี้ไปยัง main entry ของคุณ

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

WARNING

โปรดใช้อย่างระมัดระวัง ภายในเราใช้ MutationObserver เพื่อตรวจจับการเปลี่ยนแปลง class ซึ่งหมายความว่าไม่เพียงแต่การเปลี่ยนแปลงที่คุณทำด้วยตนเอง แต่ยังรวมถึงการเปลี่ยนแปลงที่ทำโดย scripts ของคุณจะถูกตรวจจับและรวมอยู่ใน stylesheet นี่อาจทำให้เกิดความไม่ตรงกันระหว่าง dev และ production build เมื่อคุณเพิ่ม dynamic classes ตาม logic บางอย่างใน script tags เราแนะนำให้เพิ่ม dynamic parts ของคุณไปยัง safelist หรือตั้งค่า UI regression tests สำหรับ production build ของคุณหากเป็นไปได้

Frameworks

UI/App frameworks บางตัวมีข้อควรระวังที่ต้องแก้ไขเพื่อให้ทำงานได้ หากคุณกำลังใช้หนึ่งใน frameworks ต่อไปนี้ เพียงปฏิบัติตามคำแนะนำ

VanillaJS / TypeScript

เมื่อใช้ VanillaJS หรือ TypeScript คุณต้องเพิ่ม js และ ts files extensions เพื่อให้ UnoCSS อ่านและแยกวิเคราะห์เนื้อหา โดยค่าเริ่มต้น js และ ts files จะถูกยกเว้น ดูส่วน Extracting from Build Tools Pipeline

React

หากคุณใช้ @vitejs/plugin-react:

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

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

หากคุณใช้ @unocss/preset-attributify คุณควรลบ tsc ออกจาก build script

หากคุณใช้ @vitejs/plugin-react กับ @unocss/preset-attributify คุณต้องเพิ่ม plugin ก่อน @vitejs/plugin-react

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

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

คุณสามารถค้นหาโปรเจคตัวอย่าง React ที่ใช้ plugins ทั้งสองได้ในไดเรกทอรี examples/vite-react ตรวจสอบ scripts ใน package.json และ Vite config file

Preact

หากคุณใช้ @preact/preset-vite:

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

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

หรือหากคุณใช้ @prefresh/vite:

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

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

หากคุณใช้ @unocss/preset-attributify คุณควรลบ tsc ออกจาก build script

คุณสามารถค้นหาโปรเจคตัวอย่าง Preact ที่ใช้ plugins ทั้งสองได้ในไดเรกทอรี examples/vite-preact ตรวจสอบ scripts ใน package.json และ Vite config file

Svelte

plugin ต้องถูกเพิ่มก่อน @sveltejs/vite-plugin-svelte

เพื่อรองรับ class:foo และ class:foo={bar} เพิ่ม plugin และกำหนดค่า extractorSvelte ในตัวเลือก extractors

คุณสามารถใช้ simple rules สำหรับ class: เช่น class:bg-red-500={foo} หรือใช้ shortcuts ที่มีหลาย rules ดู src/App.svelte ในโปรเจคตัวอย่างที่เชื่อมโยงด้านล่าง

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

Sveltekit

เพื่อรองรับ class:foo และ class:foo={bar} เพิ่ม plugin และกำหนดค่า extractorSvelte ในตัวเลือก extractors

คุณสามารถใช้ simple rules สำหรับ class: เช่น class:bg-red-500={foo} หรือใช้ shortcuts ที่มีหลาย rules ดู src/routes/+layout.svelte ในโปรเจคตัวอย่างที่เชื่อมโยงด้านล่าง

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

Web Components

เพื่อทำงานกับ web components คุณต้องเปิดใช้งาน shadow-dom mode บน plugin

อย่าลืมลบ import สำหรับ uno.css เนื่องจาก shadow-dom mode จะไม่เปิดเผยมันและแอปพลิเคชันจะไม่ทำงาน

import UnoCSS from 'unocss/vite'

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

ในแต่ละ web component เพียงเพิ่ม @unocss-placeholder ไปยัง style CSS block ของมัน:

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
  `
  // ...
}

คุณมีโปรเจคตัวอย่าง Web Components ในไดเรกทอรี examples/vite-lit

::part built-in support

คุณสามารถใช้ ::part เนื่องจาก plugin รองรับผ่าน shortcuts และใช้ rule part-[<part-name>]:<rule|shortcut> จาก preset-mini เช่นการใช้กับ simple rules เช่น part-[<part-name>]:bg-green-500 หรือใช้บาง shortcut: ตรวจสอบ src/my-element.ts ในโปรเจคตัวอย่างที่เชื่อมโยงด้านล่าง

part-[<part-name>]:<rule|shortcut> จะทำงานเฉพาะกับ plugin นี้โดยใช้ shadow-dom mode

plugin ใช้ nth-of-type เพื่อหลีกเลี่ยงการชนกันกับหลาย parts ใน web component เดียวกันและสำหรับ parts เดียวกันบน web components ที่แตกต่างกัน คุณไม่ต้องกังวลเกี่ยวกับมัน plugin จะดูแลให้คุณ

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

จากนั้นใน 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

คุณต้องเพิ่ม vite-plugin-solid plugin หลังจาก UnoCSS's plugin

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

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

คุณสามารถค้นหาโปรเจคตัวอย่าง Solid ในไดเรกทอรี examples/vite-solid

Elm

คุณต้องเพิ่ม vite-plugin-elm plugin ก่อน UnoCSS's plugin

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

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

คุณสามารถค้นหาโปรเจคตัวอย่าง Elm ในไดเรกทอรี examples/vite-elm

Examples

Basic Example

คุณสามารถค้นหาโปรเจคตัวอย่าง Vite พื้นฐานในไดเรกทอรี examples/vite-basic

Framework Examples

เรามีโปรเจคตัวอย่างสำหรับ frameworks ต่างๆ:

• Vite React Example
• Vite Preact Example
• Vite Svelte Example
• Vite Vue Example

Performance