インストール

プレーンViteとInertiaの両方に対応した、VueアプリケーションにNuxt UIをインストールおよび設定する方法を学びます。

Setup

Vueプロジェクトに追加

Nuxt UIパッケージをインストールする

pnpm add @nuxt/ui tailwindcss

yarn add @nuxt/ui tailwindcss

npm install @nuxt/ui tailwindcss

bun add @nuxt/ui tailwindcss

x`vite.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 buildrun-p type-check "build-only {@}"と並列に実行します。したがって、クリーンチェックアウトではファイルが存在する前にタイプチェックが開始され、Cannot find name 'useToast'のようなエラーで失敗することがあります。代わりにビルド後にタイプチェックを実行して、宣言が最初に生成されるようにしてください。

package.json

{
  "scripts": {
    "build": "run-s build-only type-check"
  }
}

内部的には、Nuxt UIはテーマタイプを解決するためにカスタムエイリアスに依存しています。TypeScriptを使用している場合は、vite.config.tsで自動補完を有効にするために、これらのエイリアスをtsconfigファイルに追加してください。

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

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>

Appコンポーネントはグローバル設定を設定し、Toast、Tooltip、promatic overlaysに必要です。

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

これにより、スタイルがアプリにスコープされ、オーバーレイやスタックコンテキストの問題を防ぎます。

Vueテンプレートを使う

公式テンプレートをGitHubまたはCLIのUse this templateボタンを使用して開始します。

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

Starter

Nuxt UIを使い始めるための最小限のテンプレートです。

Dashboard

高度な管理インターフェイスを構築するための複数列レイアウトのダッシュボードテンプレート。

Chat

Vercel AI SDKを搭載した独自のチャットボットを構築するためのAIチャットボットテンプレート。

Starter Adonis

Inertia.jsを使用したAdonisJS用の最小限のNuxt UIテンプレート。

Starter Laravel

Inertia.jsを使用したLaravel用の最小限のNuxt UIテンプレートです。

Options

vite.config.tsでオプションを提供することで、Nuxt UIをカスタマイズできます。

`prefix`

コンポーネントのプレフィックスを変更するには、prefixオプションを使用します。

デフォルト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`

Nuxt UIの設定を提供するには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のデフォルトのpropsを設定し、ビルド時にclientBundleを通してアイコンをバンドルする設定をします。Nuxt UI自身のアイコンのバンドルは、コレクションがインストールされたときにデフォルトで有効になります。オプトアウトするにはclientBundle: 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({
      icon: {
        mode: 'svg',
        clientBundle: {
          scan: true
        }
      }
    })
  ]
})

アイコンコレクションとクライアントバンドルの詳細については、Iconsのドキュメントを参照してください。

`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オプションを使用して、コンポーネントテーマの生成に使用される動的カラーエイリアスを定義します。

デフォルト['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を保持します。バリデーションスタイルはerrorに依存します。

色のカスタマイズとテーマの詳細については、テーマセクションをご覧ください。

`theme.transitions`

theme.transitionsオプションを使用して、コンポーネントのトランジションを有効または無効にします。

デフォルト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を通じて提供するクラスのみを保持します。

デフォルト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オプションを使用して、コンポーネントのデフォルトのcolorおよびsizeバリアントをオーバーライドします。

デフォルト値はprimaryまたはmdのみ置き換えられるため、Avatarはcolor: 'neutral'を保持し、Separatorはsize: 'xs'を保持します。

デフォルト{ 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>

接頭辞の使用については、Tailwind CSSドキュメントを参照してください。

`prose`

proseオプションを使用して、Nuxt UI Proseコンポーネントとそのテーマを有効にします。

デフォルト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オプションを使用して、構成可能な自動インポートを無効にするか、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`

コンポーネントの自動インポートを無効にするか、unplugin-vue-componentsオプションをカスタマイズするには、componentsオプションを使用します。

デフォルト{}

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"}

ルーティング統合を構成するには、routerオプションを使用します。これは、Electronアプリケーション、MPA、Inertia.jsや[Hybridly](xph74xxph75xのようなフレームワークなど、vue-routerを使用しないアプリケーションに便利です。

デフォルトtrue

値	説明
`true`	`RouterLink`コンポーネントでのナビゲーションに`vue-router`を使用。
`false`	ルーティング統合を無効にし、リンクをプレーン`<a>`タグとしてレンダリング。
`'inertia'`	`Link`コンポーネントのナビゲーションにInertia.jsを使用します。

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

Hybridlyのようなフレームワークにカスタムナビゲーションロジックを提供するには、Vite設定でrouter: falseを設定し、Vueプラグインをインストールするときに関数を渡すことができます。

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"}

Nuxt UIが.nuxt-uiディレクトリを生成するディレクトリをオーバーライドするには、rootオプションを使用します。デフォルトではViteのrootを使用しますが、electron-viteのようなセットアップでは、レンダラーのrootはサブディレクトリを指します。（例：src/renderer）のため、Tailwindがスキャンしないsrc/renderer/node_modules/.nuxt-uiにテンプレートが表示され、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

デフォルトfalse
タイプ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="..." />のように静的に解析できない動的コンポーネントに便利です。

新しく使用したコンポーネントは、次の開発サーバ起動時にピックアップされます。コンポーネントを追加してスタイルがない場合は、開発サーバを再起動してください。

連続リリース

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に自動的にコメントし、変更を簡単にテストできます。

Introduction

Nuxt UI is a comprehensive Vue UI component library (Nuxt optional), offering 125+ accessible, Tailwind CSS components for building modern web applications.

Migration

A comprehensive guide to migrate your application from Nuxt UI v3 to Nuxt UI v4.