Vue 응용 프로그램에서 Nuxt UI를 설치하고 구성하는 방법을 알아보고, 일반 Vite 및 Inertia와 호환됩니다.
Setup 설정
Vue 프로젝트에 추가
Nuxt UI 패키지 설치하기
pnpm add @nuxt/ui tailwindcss
yarn add @nuxt/ui tailwindcss
npm install @nuxt/ui tailwindcss
bun add @nuxt/ui tailwindcss
xxvite.config.ts에 Nuxt UI Vite 플러그인 추가
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui()
]
})
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import laravel from 'laravel-vite-plugin'
export default defineConfig({
plugins: [
laravel({
input: ['resources/js/app.ts'],
refresh: true
}),
vue({
template: {
transformAssetUrls: {
base: null,
includeAbsolute: false
}
}
}),
ui({
router: 'inertia'
})
]
})
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
import adonisjs from '@adonisjs/vite/client'
import inertia from '@adonisjs/inertia/client'
export default defineConfig({
plugins: [
adonisjs({
entrypoints: ['inertia/app/app.ts'],
reload: ['resources/views/**/*.edge']
}),
inertia(),
vue(),
ui({
router: 'inertia'
})
]
})
Nuxt UI는
unplugin-auto-import 및 unplugin-vue-components를 등록하고 auto-imports.d.ts 및 components.d.ts 형식 선언 파일을 생성합니다. 이 파일을 gitignore하여 tsconfig에 추가하는 것이 좋습니다.tsconfig.app.json
{
"include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}
.gitignore
# Auto-generated type declarations
auto-imports.d.ts
components.d.ts
이러한 선언 파일은 vite가 실행될 때만 작성됩니다. 기본
create-vuebuild 스크립트는 vue-tsc를 vite build (run-p type-check "build-only {@}")와 병렬로 실행하므로, 깨끗한 체크 아웃 유형 검사는 파일이 존재하기 전에 시작되고 Cannot find name 'useToast'와 같은 오류가 발생하여 실패합니다. 대신 빌드 후에 유형 검사를 실행하여 선언이 먼저 생성됩니다.package.json
{
"scripts": {
"build": "run-s build-only type-check"
}
}
내부적으로 Nuxt UI는 사용자 정의 별칭을 사용하여 테마 유형을 확인합니다. TypeScript를 사용하는 경우
tsconfig 파일에 이러한 별칭을 추가하여 vite.config.ts에서 자동 완성을 가능하게 합니다.tsconfig.node.json
{
"compilerOptions": {
"paths": {
"#build/ui": [
"./node_modules/.nuxt-ui/ui"
]
}
}
}
tsconfig.app.json
{
"compilerOptions": {
"paths": {
"#build/ui/*": [
"./node_modules/.nuxt-ui/ui/*"
]
}
}
}
Nuxt UI Vue 플러그인 사용하기
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'
const app = createApp(App)
const router = createRouter({
routes: [],
history: createWebHistory()
})
app.use(router)
app.use(ui)
app.mount('#app')
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'
const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'
createInertiaApp({
title: title => (title ? `${title} - ${appName}` : appName),
resolve: name =>
resolvePageComponent(
`./pages/${name}.vue`,
import.meta.glob<DefineComponent>('./pages/**/*.vue')
),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.use(ui)
.mount(el)
}
})
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'
const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'
createInertiaApp({
title: title => (title ? `${title} - ${appName}` : appName),
resolve: name =>
resolvePageComponent(
`../pages/${name}.vue`,
import.meta.glob<DefineComponent>('../pages/**/*.vue')
),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.use(ui)
.mount(el)
}
})
Import Tailwind CSS 및 Nuxt UI CSS에서
@import "tailwindcss";
@import "@nuxt/ui";
@import "tailwindcss";
@import "@nuxt/ui";
@import "tailwindcss";
@import "@nuxt/ui";
엔트리 포인트에서 CSS 파일을 가져옵니다.
import './assets/css/main.css'
import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import ui from '@nuxt/ui/vue-plugin'
import App from './App.vue'
const app = createApp(App)
const router = createRouter({
routes: [],
history: createWebHistory()
})
app.use(router)
app.use(ui)
app.mount('#app')
import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'
const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Nuxt UI'
createInertiaApp({
title: title => (title ? `${title} - ${appName}` : appName),
resolve: name =>
resolvePageComponent(
`./pages/${name}.vue`,
import.meta.glob<DefineComponent>('./pages/**/*.vue')
),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.use(ui)
.mount(el)
}
})
import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import ui from '@nuxt/ui/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'
const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Nuxt UI'
createInertiaApp({
title: title => (title ? `${title} - ${appName}` : appName),
resolve: name =>
resolvePageComponent(
`../pages/${name}.vue`,
import.meta.glob<DefineComponent>('../pages/**/*.vue')
),
setup({ el, App, props, plugin }) {
createApp({ render: () => h(App, props) })
.use(plugin)
.use(ui)
.mount(el)
}
})
VSCode용 Tailwind CSS IntelliSense 확장을 설치하고 다음 설정을 추가하는 것이 좋습니다.
.vscode/settings.json
{
"files.associations": {
"*.css": "tailwindcss"
},
"editor.quickSuggestions": {
"strings": "on"
},
"tailwindCSS.classAttributes": ["class", "ui"],
"tailwindCSS.classFunctions": ["defineAppConfig"]
}
App 구성 요소를 사용하여 앱 래핑
<template>
<UApp>
<RouterView />
</UApp>
</template>
<template>
<UApp>
<!-- Your content goes here -->
</UApp>
</template>
<template>
<UApp>
<!-- Your content goes here -->
</UApp>
</template>
x루트 컨테이너에 isolate 클래스를 추가합니다.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Nuxt UI</title>
</head>
<body>
<div id="app" class="isolate"></div>
<script type="module" src="/src/main.ts"></script>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
@inertiaHead
@vite('resources/js/app.ts')
</head>
<body>
<div class="isolate">
@inertia
</div>
</body>
</html>
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
@inertiaHead()
@vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
</head>
<body>
@inertia({ class: 'isolate' })
</body>
</html>
이렇게 하면 스타일이 앱으로 범위가 지정되고 오버레이 및 스택 컨텍스트의 문제가 방지됩니다.This ensures styles are scoped to your app and prevents issues with overrides and stacking contexts.
Vue 템플릿 사용하기
GitHub 또는 CLI에서 Use this template 버튼을 사용하여 official templates 중 하나를 시작하십시오.
npm create nuxt@latest -- --no-modules -t ui-vue
npm create nuxt@latest -- --no-modules -t ui-vue/dashboard
npm create nuxt@latest -- --no-modules -t ui-vue/chat
옵션
vite.config.ts에서 옵션을 제공하여 Nuxt UI를 사용자 정의할 수 있습니다.
prefix (### prefix)
prefix 옵션을 사용하여 구성 요소의 접두어를 변경합니다.
- Default:
U
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
prefix: 'Nuxt'
})
]
})
ui (### ui)
ui 옵션을 사용하여 Nuxt UI에 대한 구성을 제공합니다. Nuxt의 app.config.ts에 있는 ui 키에 해당하는 Vue 기능입니다.
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
ui: {
colors: {
primary: 'green',
neutral: 'slate'
}
}
})
]
})
dts 공식
dts 옵션을 사용하여 자동으로 가져온 구성 요소 및 합성 파일에 대한 선언 파일 생성을 활성화하거나 비활성화합니다.
- 기본값:
true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
dts: false
})
]
})
icon 공식
icon 옵션을 사용하여 Icon 구성 요소(size, mode, customize)에 대한 기본 소품을 설정하고 clientBundle를 통한 빌드 타임 아이콘 번들링을 구성합니다. Nuxt UI 자체 아이콘의 번들링은 기본적으로 설정되어 있습니다.
- Default:
{}
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
icon: {
mode: 'svg',
clientBundle: {
scan: true
}
}
})
]
})
colorMode (### colorMode)
colorMode 옵션을 사용하여 @vueuse/core의 색상 모드 통합을 활성화하거나 비활성화합니다.
- 기본값:
true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
colorMode: false
})
]
})
theme.colors (### theme.colors)
theme.colors 옵션을 사용하여 구성요소 주제를 생성하는 데 사용할 동적 색상 별칭을 정의합니다.
- 기본값:
['primary', 'secondary', 'success', 'info', 'warning', 'error']
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
colors: ['primary', 'error']
}
})
]
})
각 별칭은 구성 요소 테마에
--ui-color-* 음영 및 변형의 전체 집합을 생성하며, 응용 프로그램에서 사용하는지 여부에 관계없이 색상 변형이 있습니다. 목록을 실제 사용하는 별칭으로 잘라내고, 유효성 검사 스타일이 의존하므로 양식을 사용하는 경우에는 error를 유지합니다.theme.transitions 파일
theme.transitions 옵션을 사용하여 구성 요소의 전환을 활성화하거나 비활성화합니다.
- Default:
true
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
transitions: false
}
})
]
})
이 옵션은 커서 또는 활성 상태가 있는 구성 요소에
transition-colors 클래스를 추가합니다.theme.unstyled : badge{label="4.9+" class="align-text-top"}
theme.unstyled 옵션을 사용하여 구성 요소에서 모든 기본 테마 클래스를 제거하고 해당 구조와 class, ui 또는 app.config.ui를 통해 제공된 클래스만 유지합니다.
- Default:
false
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
unstyled: true
}
})
]
})
이것은 structural 클래스 (포지셔닝, 전환, 플렉스 / 그리드)를 제거합니다.
Modal, Drawer 또는 Calendar와 같은 레이아웃이 무거운 구성 요소는 PrimeVue의 스타일이 지정되지 않은 모드와 비슷한 레이아웃을 다시 공급해야합니다.theme.defaultVariants (### theme.defaultVariants)
theme.defaultVariants 옵션을 사용하여 구성 요소의 기본 color 및 size 변형을 재지정합니다.
정확히 primary 또는 md인 기본값만 대체되므로 아바타는 color: 'neutral'를 유지하고 분리기는 size: 'xs'를 유지합니다.
- Default:
{ color: 'primary', size: 'md' }
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
defaultVariants: {
color: 'neutral',
size: 'sm'
}
}
})
]
})
theme.prefix : badge{label="4.2+" class="align-text-top"}
theme.prefix 옵션을 사용하여 Tailwind CSS 가져오기에서 설정한 것과 동일한 접두사를 구성합니다. 이렇게 하면 Nuxt UI 구성 요소가 올바른 접두사 유틸리티 클래스 및 CSS 변수를 사용할 수 있습니다.
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
theme: {
prefix: 'tw'
}
})
]
})
@import "tailwindcss" prefix(tw);
@import "@nuxt/ui";
이것은 Nuxt UI 컴포넌트 테마의 모든 Tailwind 유틸리티 클래스와 CSS 변수에 자동으로 접두어를 추가합니다.
<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>
<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
prose 파일
prose 옵션을 사용하여 Nuxt UI Prose components 및 해당 테마를 활성화합니다.
- Default:
false기본값
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
prose: true
})
]
})
autoImport (### autoImport)
autoImport 옵션을 사용하여 작성가능한 자동 가져오기를 비활성화하거나 unplugin-auto-import 옵션을 사용자 정의합니다.
- 기본값:
{}
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
autoImport: false
})
]
})
비활성화된 경우에도
@nuxt/ui/composables에서 명시적으로 합성 파일을 가져올 수 있습니다.components (### components)
components 옵션을 사용하여 구성요소 자동 가져오기를 비활성화하거나 unplugin-vue-components 옵션을 사용자 정의할 수도 있습니다.
- Default:
{}기본값
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
components: false
})
]
})
비활성화된 경우에도
import Button from '@nuxt/ui/components/Button.vue' 또는 import ProseCode from '@nuxt/ui/components/prose/Code.vue'와 같은 명시적으로 구성요소를 가져올 수 있습니다.router : badge{label="4.3+" class="align-text-top"} : badge{label="4.3+" class="align-text-top"}
router 옵션을 사용하여 라우팅 통합을 구성합니다. 이 옵션은 vue-router를 사용하지 않는 응용 프로그램(예: Electron 앱, MPA) 또는 ](Inertia.jshttps://inertiajs.com/) 또는 [Hybridly](xph74xxph75x와 같은 프레임워크)에 유용합니다.
- 기본값:
true
| 가치 (Value) | 설명 (Description) |
|---|---|
true (true) | RouterLink 구성 요소를 사용하여 탐색할 때 vue-router를 사용합니다. |
false (false) | 라우팅 통합을 비활성화하고 링크가 일반 <a> 태그로 렌더링됩니다. |
'inertia'의 발음을 'inertia'xph788 | Inertia.js를 사용하여 Link 구성 요소로 탐색합니다. |
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
router: false
})
]
})
Vite 설정에서
router: false를 설정하고 Vue 플러그인을 설치할 때 함수를 전달하여 Hybridly와 같은 프레임워크에 사용자 지정 탐색 로직을 제공할 수 있습니다.src/main.ts
import ui from '@nuxt/ui/vue-plugin'
import { router } from 'hybridly'
app.use(ui, {
router: (event, { href, external }) => {
if (external) {
return
}
event.preventDefault()
router.navigate({ url: href })
}
})
false 또는 'inertia'로 설정하면 vue-router는 종속성으로 필요하지 않습니다.scanPackages : badge{label="4.3+" class="align-text-top"}
scanPackages 옵션을 사용하여 Nuxt UI를 사용하여 구성 요소를 검색해야 하는 추가 npm 패키지를 지정할 수 있습니다. 이 기능은 내부적으로 Nuxt UI 구성 요소를 사용하는 공유 구성 요소 라이브러리가 있는 경우 유용합니다.
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
scanPackages: ['@my-org/ui-components']
})
]
})
기본적으로
@nuxt/ui만 스캔됩니다. 외부 패키지에 Nuxt UI를 사용하는 Vue 구성 요소가 포함되어 있을 때 이 옵션을 사용하십시오.root : badge{label="4.9+" class="align-text-top"}
root 옵션을 사용하여 Nuxt UI가 .nuxt-ui 디렉토리를 생성하는 디렉토리를 재정의합니다. 기본적으로 Viite의 root를 사용하지만, electron-vite와 같은 설정에서는 렌더러의 root가 하위 디렉토리를 가리킵니다.(예를 들어 src/renderer) 템플릿이 src/renderer/node_modules/.nuxt-ui에 착륙하여 Tailwind가 스캔하지 않으므로 bg-default, ring-default 및 divide-default와 같은 테마 클래스가 누락됩니다.
electron.vite.config.ts
import { defineConfig } from 'electron-vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
renderer: {
root: 'src/renderer',
plugins: [
vue(),
ui({
root: __dirname
})
]
}
})
프로젝트 루트에
root를 가리키면 생성된 .nuxt-ui 디렉토리가 Tailwind가 스캔하는 node_modules로 끝납니다.experimental.componentDetection : badge{label="4.11+" class="align-text-top"}
experimental.componentDetection 옵션을 사용하여 트리 셰이킹을 위한 자동 구성 요소 감지를 활성화합니다. 이 기능은 소스 코드를 스캔하여 실제로 사용되는 구성 요소를 감지하고 해당 구성 요소에 필요한 CSS만 생성합니다.(종속성 포함). 그것이 없으면, Vite 플러그인은 모든 구성요소에 대한 테마 CSS를 생성합니다. 탐지는 Vite 루트를 덮습니다. scanPackages에 나열된 패키지와 루트 외부에 있는 components 옵션의 dirs에 나열된 패키지입니다.
- Default:
false - Type :
boolean | string[]
**자동 감지 기능 사용: **
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
experimental: {
componentDetection: true
}
})
]
})
**동적 사용을 위한 추가 구성요소 포함: **
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'
export default defineConfig({
plugins: [
vue(),
ui({
experimental: {
componentDetection: ['Modal', 'DropdownMenu', 'Popover']
}
})
]
})
구성 요소 이름 배열을 제공하면 자동 탐지가 활성화되고 이러한 구성 요소는 종속성과 함께 포함됩니다. 정적으로 분석할 수 없는
<component :is="..." />와 같은 동적 구성 요소에 유용합니다.새로 사용된 구성 요소는 다음 dev-server 시작 시 선택됩니다. 구성 요소를 추가하고 해당 스타일이 누락된 경우 dev 서버를 다시 시작하십시오.
Continuous 출시
Nuxt UI는 pkg.pr.new를 사용하여 지속적인 미리 보기 릴리스를 제공하므로 개발자가 공식 릴리스를 기다리지 않고도 최신 기능과 버그 수정에 즉시 액세스할 수 있습니다.
v4 분기에 대한 모든 커밋 및 PR에 대해 자동 미리 보기 릴리스가 생성됩니다. 패키지 버전을 특정 커밋 해시 또는 PR 번호로 대체하여 사용합니다.
package.json
{
"dependencies": {
- "@nuxt/ui": "^4.0.0",
+ "@nuxt/ui": "https://pkg.pr.new/@nuxt/ui@4c96909",
}
}
pkg.pr.new는 설치 URL을 사용하여 PR에 자동으로 주석을 추가하여 변경 사항을 쉽게 테스트할 수 있습니다.