---
contentId: 8b808104-15ac-42ca-9535-cef0996ddf66
part: 7
title: "Enhancing Integration with Unplugin and Nuxt Module"
description: "Discover how to seamlessly integrate a Vue.js component library using Unplugin Vue Components and Nuxt Module, enhancing usability and developer experience."
date: 2024-11-24
seriesSlug: the-complete-guide-to-building-a-vue-js-component-library
---

Having a robust component library is a great start, but integrating it into the **Vue.js ecosystem** takes it to another level. In this ecosystem, two main tools stand out:

1. [**Unplugin Vue Components**](https://github.com/unplugin/unplugin-vue-components): A bundler plugin for on-demand components that are auto-imported, fully typed, and tree-shakable.
2. [**Nuxt**](https://nuxt.com): An open-source framework based on Vue.js that simplifies and empowers web development.

Although our component library can function without integration into these tools, I'm firmly convinced that integration will enhance its power and ease of use. I'm devoted to providing the best developer experience possible, and I'm sure you will find it invaluable.

## Unplugin Vue component resolver

Before building the resolver, it's essential to understand how **Unplugin Vue Components** works. This will clarify what a resolver does and its functionality.



> [!TIP]
> If you have any questions, please comment below, and I'll be happy to assist.



Consider this component:

```vue [Example]
<script lang="ts" setup>
</script>

<template>
  <UButton label="Click me" />
</template>
```

Notice that there's no import statement for the `UButton` component. Unplugin Vue Components scans the template and identifies non-standard HTML tags to find them in its component list. This list can be manually fed or automatically populated using a resolver.

A resolver is a function that receives a component name and returns its import path if it matches the resolver's internal list. This allows selective auto-import of components or adding prefixes to component names.

In our example, a resolver might resolve the `UButton` component as:

```ts [Example]
return {
  name: 'Button',
  from: '@nuxt/ui'
}
```

Unplugin Vue Components would transform the component by injecting the import statement:

```vue [Example]
<script lang="ts" setup>
import { Button as UButton } from '@nuxt/ui'
</script>

<template>
  <UButton label="Click me" />
</template>
```

Simple, right? Now, let's build our resolver.



> [!NOTE]
> To deepen your understanding of Vite, try the [vite-plugin-inspector](https://github.com/antfu-collective/vite-plugin-inspect), which lets you inspect modifications made by each plugin.



### Building the resolver

First, gather all your library components in a `src/components.ts` file within the `packages/huchet-vue` folder:

```bash [src/components.ts]
touch src/components.ts
```

Then export an array of all components:

```ts [Example]
export const components = [
  'Button'
]
```

To ensure updates, create a test that verifies the exported components match those in the `components` folder. Create a `src/index.test.ts` file in `packages/huchet-vue`:

```bash [src/index.test.ts]
touch src/index.test.ts
```

Add this test to verify component exports:

```ts [Example]
import { expect, it } from 'vitest'
import { components } from './components'
import * as Huchet from './index'

it('should expose the correct components', () => {
  expect(Object.keys(Huchet)).toEqual(Object.values(components))
})
```

This test prevents missed updates when components change.



> [!NOTE]
> Inspired by [Radix Vue](https://github.com/unovue/radix-vue/blob/main/packages/radix-vue/src/index.test.ts).



Next, create a `src/resolver.ts` for the Unplugin Vue Components resolver and install it as a dev dependency:

```bash [src/resolver.ts]
touch src/resolver.ts && pnpm add -D unplugin-vue-components
```

The resolver function initiates in `vite.config.ts`, allowing developers to pass options like a prefix for component names. It resolves component names and returns import paths if they match:

```ts [vite.config.ts]
import type { ComponentResolver } from 'unplugin-vue-components'
import { components } from './components'

export interface ResolverOptions {
  /**
   * prefix for components used in templates
   *
   * @defaultValue ""
   */
  prefix?: string
}

export default function (options: ResolverOptions = {}): ComponentResolver {
  const { prefix = '' } = options

  return {
    type: 'component',
    resolve: (name: string) => {
      if (name.toLowerCase().startsWith(prefix.toLowerCase())) {
        const componentName = name.substring(prefix.length)
        if (components.includes(componentName)) {
          return {
            name: componentName,
            from: '@barbapapazes/huchet-vue',
          }
        }
      }
    },
  }
}
```

To ensure the resolver is built, add it as an entry point in `vite.config.ts`:

```ts [vite.config.ts]
import { resolve } from 'node:path'
import { defineConfig } from 'vite'

export default defineConfig({
  build: {
    lib: {
      entry: {
        index: resolve(__dirname, 'src/index.ts'),
        resolver: resolve(__dirname, 'src/resolver.ts'), // [!code ++]
      },
    },
  },
})
```

Finally, export the resolver in `package.json`:

```json [package.json]
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs"
    },
    "./resolver": { // [!code ++]
      "types": "./dist/resolver.d.ts", // [!code ++]
      "import": "./dist/resolver.mjs" // [!code ++]
    }
  },
  "main": "./dist/index.mjs",
  "types": "dist/index.d.ts"
}
```



> [!NOTE]
> Rebuild the project to ensure the new entry point is accessible.



### Using the resolver

With the resolver ready, let's test it in our playground project:

1. Navigate to the playground folder:

```bash [terminal]
cd ../../playground/vue
```

2. Install `unplugin-vue-components`:

```bash [terminal]
pnpm add -D unplugin-vue-components
```

3. Update `vite.config.ts` to use the resolver with a `U` prefix:

```ts [vite.config.ts]
import HuchetVueResolver from '@barbapapazes/huchet-vue/resolver'
import Vue from '@vitejs/plugin-vue'
import Components from 'unplugin-vue-components/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    Vue(),
    Components({
      dts: true,
      resolvers: [
        HuchetVueResolver({
          prefix: 'U'
        }),
      ],
    })
  ],
})
```

4. Add `components.d.ts` to `.gitignore`:

```bash [components.d.ts]
echo "components.d.ts" >> .gitignore
```



> [!NOTE]
> This file is generated by `unplugin-vue-components` to help your IDE understand the components and provide auto-completion.



5. Update `src/App.vue` to use the `UButton` component without importing it:

```vue [src/App.vue]
<template>
  <div class="flex gap-6 p-6">
    <UButton label="Hello World" />
    <UButton label="Hello World" variant="outline" />
  </div>
</template>
```

That's it! The `UButton` component is automatically imported for ease of use.

## Nuxt module

Nuxt transforms web development with Vue.js by providing an extended configuration and module system. Building a Nuxt module for our component library requires minimal effort and eliminates setup for developers. Let's dive into it.

### Building the module

Start by creating a `nuxt.ts` file in the `packages/huchet-vue` folder:

```bash [nuxt.ts]
touch nuxt.ts
```

Install the necessary Nuxt packages and Tailwind CSS:

```bash [terminal]
pnpm add -D @nuxt/kit @nuxt/schema && pnpm add tailwindcss@next @tailwindcss/vite@next @tailwindcss/postcss@next
```

Then, create the module:

```ts [Example]
import type { } from '@nuxt/schema' // Mandatory to avoid a bug when building
import { addComponent, addVitePlugin, defineNuxtModule } from '@nuxt/kit'

import { components } from './components'

export interface ModuleOptions {
  prefix: string
}

export default defineNuxtModule<ModuleOptions>({
  meta: {
    name: '@barbapapazes/huchet-vue',
    configKey: 'huchet',
    compatibility: {
      nuxt: '>=3.0.0',
    },
  },
  defaults: {
    prefix: '',
  },
  async setup(options, nuxt) {
    if (nuxt.options.builder === '@nuxt/vite-builder') {
      const Tailwind = await import('@tailwindcss/vite').then(r => r.default)
      addVitePlugin(Tailwind())
    }
    else {
      nuxt.options.postcss.plugins['@tailwindcss/postcss'] = {}
    }

    for (const component of components) {
      addComponent({
        name: `${options.prefix}${component}`,
        export: component,
        filePath: '@barbapapazes/huchet-vue',
      })
    }
  },
})
```

This plugin simplifies Tailwind CSS setup, using either Vite or PostCSS depending on the Nuxt builder.

The second part auto-imports components into the Nuxt system using the Unimport framework, allowing prefix customization like the Unplugin Vue Components resolver.

Inspired by [Radix Vue Nuxt module](https://github.com/unovue/radix-vue/tree/main/packages/plugins/src/nuxt) and [Nuxt UI 3 module](https://github.com/nuxt/ui).

Add an entry in `vite.config.ts` and export it in `package.json`:

```ts [package.json]
import { resolve } from 'node:path'

export default defineConfig({
  build: {
    lib: {
      entry: {
        index: resolve(__dirname, 'src/index.ts'),
        resolver: resolve(__dirname, 'src/resolver.ts'),
        nuxt: resolve(__dirname, 'src/nuxt.ts'), // [!code ++]
      },
    },
    rollupOptions: {
      external: ['vue', '@nuxt/kit', '@tailwindcss/vite'], // [!code ++]
    },
  },
})
```

Make sure to externalize `@nuxt/kit` and `@tailwindcss/vite`.

```json [Example]
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs"
    },
    "./resolver": {
      "types": "./dist/resolver.d.ts",
      "import": "./dist/resolver.mjs"
    },
    "./nuxt": {
      "types": "./dist/nuxt.d.ts",
      "import": "./dist/nuxt.mjs"
    }
  },
  "main": "./dist/index.mjs",
  "types": "dist/index.d.ts"
}
```

### Using the module

With the Nuxt module in place, let's set up a way to test its functionality. We'll create a new Nuxt playground, install the package, and configure it.

1. Create a new Nuxt project from the root directory:

```bash [terminal]
npx nuxi init ./playground/nuxt
```



> [!NOTE]
> Modify the `postinstall` script to `dev:prepare` in Nuxt's `package.json` to avoid errors after a package installation. Rename it since `prepare` is reserved by npm.



2. Install the component library:

```bash [package.json]
cd ./playground/nuxt && pnpm add ../../packages/huchet-vue
```

3. Duplicate the `App.vue` from the Vue playground to the Nuxt playground:

```bash [App.vue]
cp ../vue/src/App.vue ./app.vue
```

4. Add the module in `nuxt.config.ts`:

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  modules: ['@barbapapazes/huchet-vue/nuxt'],
  css: ['~/assets/css/main.css'],
  huchet: {
    prefix: 'U',
  },
  compatibilityDate: '2024-11-01',
  devtools: { enabled: true },
})
```



> [!NOTE]
> Include the CSS file using the `css` property for Tailwind CSS to function.



5. Create the CSS file in `assets/css/main.css`:

```bash [assets/css/main.css]
mkdir -p assets/css && touch assets/css/main.css && echo "@import 'tailwindcss';" >> assets/css/main.css
```

6. Launch the Nuxt project:

```bash [terminal]
pnpm dev
```

Voila! You can now use the component library in a Nuxt project seamlessly, with auto-imported components and fully-functional Tailwind CSS.

The **Nuxt** developer experience, enriched by the module system, significantly simplifies developers' lives. I'm confident you will appreciate it too.
