---
title: "Client Bundle"
description: "Ship the icons you use with the client to avoid network requests."
canonical_url: "https://nuxt-git-feat-module-docs-nuxt-js.vercel.app/modules/icon/guide/client-bundle"
---
# Client Bundle

> Ship the icons you use with the client to avoid network requests.

For icons that you know you are going to use frequently, you can bundle them with your client bundle to avoid network requests.

## Prefetch (Preload) Icons

If you want icons to be available on first render, use the client bundle as the prefetch mechanism:

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon',
  ],
  icon: {
    clientBundle: {
      // Explicitly pre-bundle known icons
      icons: ['uil:github', 'heroicons:home'],
      // Keep disabled if you only want explicit entries
      scan: false,
    },
  },
})
```

You can also enable static scanning to pre-bundle icons referenced literally in your source files:

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon',
  ],
  icon: {
    clientBundle: {
      // Automatically includes statically-detected icon usages
      scan: true,
      // Keep explicit entries for dynamic icon names
      icons: ['uil:github'],
    },
  },
})
```

If you want to disable runtime icon fetching entirely, see [Disabling Runtime Fetching](#disabling-runtime-fetching) for the `provider: 'none'` + client bundle pattern.

> [!TIP]
> Static scanning only detects literal icon names. See [Scan Components](#scan-components) for details and examples, and [Rendering Icons in Component Tests](#rendering-icons-in-component-tests) for test-environment setup.

## Available Options

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    clientBundle: {
      // list of icons to include in the client bundle
      icons: [
        'uil:github',
        'logos:vitejs'
      ],

      // scan all components in the project and include icons 
      scan: true,

      // include all custom collections in the client bundle
      includeCustomCollections: true, 

      // guard for uncompressed bundle size, will fail the build if exceeds
      sizeLimitKb: 256,
    },
  },
})
```

`includeCustomCollections` will include all the custom collections you have defined in `icon.customCollections` in the client bundle. It's disabled by default when both sides of `provider` use `server`, and enabled otherwise (e.g. when `ssr: false` is set).

## Scan Components

When `scan` is enabled, the module will scan all the components in your project and include the icons used in the client bundle. This would significantly reduce the number of network requests needed for statically known icons, but might also increase the client bundle size depending on the number of icons used in your project.

You can also fine-tune tine scanning targets like:

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    clientBundle: {
      scan: {
        // note that when you specify those values, the default behavior will be overridden
        globInclude: ['components/**/*.vue', /* ... */],
        globExclude: ['node_modules', 'dist', /* ... */],
      },
    },
  },
})
```

> [!TIP]
> Scanning is relying on static analysis, which means only literal usages will be detected. Avoid constructing the icon name dynamically whenever possible.
>
> ```vue
> <template>
>   <!-- Avoid this -->
>   <Icon :name="`carbon:${dark ? 'moon' : 'sun'}`" />
>
>   <!-- Prefer this -->
>   <Icon :name="dark ? 'carbon:moon' : 'carbon:sun'" />
> </template>
> ```


## Sitemap

See the full [sitemap](https://nuxt-git-feat-module-docs-nuxt-js.vercel.app/sitemap.md) for all pages.