From 0ac570888591352cc9cdec8396299b35a849503d Mon Sep 17 00:00:00 2001 From: barbapapazes Date: Sat, 3 May 2025 12:21:22 +0200 Subject: [PATCH] docs(nuxt): add guide --- packages/.vitepress/config.mts | 4 + packages/usage/nuxt-integration-guide.md | 188 +++++++++++++++++++++++ packages/usage/vite-integration-guide.md | 3 - 3 files changed, 192 insertions(+), 3 deletions(-) create mode 100644 packages/usage/nuxt-integration-guide.md diff --git a/packages/.vitepress/config.mts b/packages/.vitepress/config.mts index 4abd9d3..4a59a3d 100644 --- a/packages/.vitepress/config.mts +++ b/packages/.vitepress/config.mts @@ -70,6 +70,10 @@ export default defineConfig({ text: 'Vite Integration Guide', link: '/usage/vite-integration-guide', }, + { + text: 'Nuxt Integration Guide', + link: '/usage/nuxt-integration-guide', + }, ], }, ], diff --git a/packages/usage/nuxt-integration-guide.md b/packages/usage/nuxt-integration-guide.md new file mode 100644 index 0000000..be61a4f --- /dev/null +++ b/packages/usage/nuxt-integration-guide.md @@ -0,0 +1,188 @@ +# Nuxt Integration Guide + +This guide explains how to integrate Vue UI into a Nuxt application. It assumes you already have a fresh Nuxt project. If not, you can create one using the following command: + +```bash +npm create nuxt@latest +``` + +Before going further, you need to install the required dependencies. + +```bash [pnpm] +pnpm add reka-ui tailwind-variants @vueuse/core @vueuse/shared @vueuse/integrations colortranslator defu fuse.js ohash embla-carousel embla-carousel-auto-height embla-carousel-auto-scroll embla-carousel-autoplay embla-carousel-class-names embla-carousel-fade embla-carousel-vue embla-carousel-wheel-gestures vue-component-type-helpers +``` + +## Configuring Nuxt + +To ensure everything works seamlessly, you need to adjust the Nuxt configuration for dependency optimization, component resolution, and TypeScript paths. + +Add the following configuration to your `nuxt.config.ts` file: + +```ts [nuxt.config.ts] +import { fileURLToPath } from 'node:url' +import tailwindcss from '@tailwindcss/vite' + +export default defineNuxtConfig({ + // ... + + future: { + compatibilityVersion: 4 + }, + + components: { + dirs: [ + '~/ui/components', + ], + }, + + imports: { + dirs: [ + 'ui/composables', + ] + }, + + typescript: { + tsConfig: { + compilerOptions: { + paths: { + '@/ui': [ + '../app/ui', + ], + } + } + } + }, + + css: ['~/assets/css/main.css'], + + vite: { + plugins: [ + tailwindcss(), + ], + optimizeDeps: { + include: ['reka-ui', 'tailwind-variants', '@vueuse/shared', '@vueuse/core'] + }, + resolve: { + alias: { + '@/ui': fileURLToPath(new URL('./app/ui', import.meta.url)), + }, + }, + }, +}) +``` + +Here are some important aspects of the configuration to help you understand its purpose and functionality: + +1. **Components Directory**: + - The `components` option specifies `~/ui/components` as a directory for auto-registering components. This eliminates the need for manual imports, making component usage more straightforward. + +2. **Imports Directory**: + - The `imports` option includes `ui/composables`, enabling automatic imports of composables from this directory. This simplifies the process of using composables throughout your project. + +3. **TypeScript Path Mapping**: + - The `typescript.tsConfig.compilerOptions.paths` setting maps the alias `@/ui` to `../app/ui`. This ensures that TypeScript correctly resolves the alias, providing accurate type checking and auto-completion in your development environment. + +4. **CSS Integration**: + - The `css` array includes `~/assets/css/main.css`, which serves as the main stylesheet for the project. This file integrates Tailwind CSS and custom styles, ensuring a consistent design system. + +5. **Vite Configuration**: + - **Plugins**: The `vite.plugins` array includes the Tailwind CSS plugin, ensuring seamless integration with the Vite build tool. + - **Dependency Optimization**: The `optimizeDeps.include` array pre-optimizes key dependencies (`reka-ui`, `tailwind-variants`, `@vueuse/shared`, `@vueuse/core`) to enhance the performance of the development server. + - **Alias Resolution**: The `resolve.alias` block maps `@/ui` to the `./app/ui` directory. This simplifies import paths and ensures consistency across the project. + +These configurations are designed to streamline development and improve the overall developer experience when working with Vue UI in a Nuxt application. + +## Setting Up Tailwind CSS + +For this section, you need to install Tailwind CSS and its dependencies: + +```bash [pnpm] +pnpm add -D tailwindcss @tailwindcss/vite @egoist/tailwindcss-icons +``` + +To style your project, integrate Tailwind CSS using its Vite plugin: + +1. Add the plugin to your `nuxt.config.ts` file (already included in the configuration above). + +2. Import Tailwind CSS in your main style file, typically `app/assets/css/main.css`: + +```css [app/assets/css/main.css] +@import "tailwindcss"; +@plugin '@egoist/tailwindcss-icons'; + +@variant light (&:where(.light, .light *)); +@variant dark (&:where(.dark, .dark *)); + +@theme default { + --color-primary: var(--ui-primary); + --color-secondary: var(--ui-secondary); + // Add other custom variables here... +} + +@layer base { + body { + @apply antialiased text-default bg-default scheme-light dark:scheme-dark; + } + + :root { + --ui-color-primary-500: var(--color-violet-500); + --ui-color-secondary-500: var(--color-blue-500); + // Define other colors and variables... + } + + .dark { + --ui-primary: var(--ui-color-primary-400); + --ui-secondary: var(--ui-color-secondary-400); + // Define dark theme variables... + } +} +``` + +This setup allows you to define light and dark themes, customize colors, and use Tailwind's built-in CSS variables. + +## Example Usage + +With everything set up, you can start using Vue UI components and composables. + +::: code-group + +```vue [app/app.vue] + + + +``` + +```vue [app/pages/index.vue] + + + +``` + +::: + +> [!NOTE] +> To prevent circular dependencies, the `App.vue` component must be explicitly imported in the `app.vue` file. This avoids issues where `app/app.vue` might attempt to auto-import itself. + +You're now ready to build your project with Vue UI! diff --git a/packages/usage/vite-integration-guide.md b/packages/usage/vite-integration-guide.md index 1ee1ab4..88f5d63 100644 --- a/packages/usage/vite-integration-guide.md +++ b/packages/usage/vite-integration-guide.md @@ -6,9 +6,6 @@ This guide explains how to integrate Vue UI into a Vite + Vue project. It assume npm create vite@latest my-vue-app --template vue-ts ``` -> [!NOTE] -> You can use any package manager of your choice (npm, yarn, pnpm, bun) to create the project. - Before going further, you need to install the required dependencies. ```bash [pnpm]