---
title: "Server Bundle"
description: "Choose how icons are bundled and served by your Nuxt server."
canonical_url: "https://nuxt-git-feat-module-docs-nuxt-js.vercel.app/modules/icon/guide/server-bundle"
---
# Server Bundle

> Choose how icons are bundled and served by your Nuxt server.

Since `@nuxt/icon` v1.0, we have introduced the server bundle concept to serve the icons from Nuxt server endpoints. This keeps the client bundle lean and able to load icons on-demand, while having all the dynamic features to use icons that might not be known at build time.

## Server Bundle Mode: `local`

This mode will bundle the icon collections you have installed locally (like `@iconify-json/*`), into your server bundle as dynamic chunks. The collection data will be loaded on-demand, only when your client request icons from that collection.

## Server Bundle Mode: `remote`

Introduced in `@nuxt/icon` v1.2, you can now use the `remote` server bundle to serve the icons from a remote CDN.

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: 'remote',
  },
})
```

Or you can specify the remote provider:

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: {
      remote: 'jsdelivr', // 'unpkg' or 'github-raw', or a custom function
    }
  },
})
```

Which will make server requests to `https://cdn.jsdelivr.net/npm/@iconify-json/ph/icons.json` to fetch the icons at runtime, instead of bundling them with your server.

Under the hood, instead of bundling `() => import('@iconify-json/ph/icons.json')` to your server bundle, it will now use something like `() => fetch('https://cdn.jsdelivr.net/npm/@iconify-json/ph/icons.json').then(res => res.json())`, where the collections are not inlined.

This would be useful when server bundle size is a concern, like in serverless or worker environments.

## Server Bundle Mode: `auto`

This is the default option, where the module will pick between `local` and `remote` based your deployment environment. `local` will be preffered unless you are deploying to a serverless or worker environment, like Vercel Edge or Cloudflare Workers.

## Externalize Icons JSON

By default, Nitro will bundle the icon collections you have installed locally (like `@iconify-json/*`), into your server bundle as dynamic chunks. When you have a large number of icons, this might make your bundling process slow and memory-intensive. You can change to externalize the icons JSON files by setting `icon.serverBundle.externalizeIconsJson` to `true`.

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    serverBundle: {
      externalizeIconsJson: true,
    }
  },
})
```

Note that this will require your production Node.js server to be able to import JSON files (Note that as in Node.js v22, [JSON modules are still an experimental feature](https://nodejs.org/api/esm.html#json-modules)). In the final build, it will contain statements like `() => import('@iconify-json/ph/icons.json', { with: { type: 'json' } })`.

Also note that in some serverless environments, like Cloudflare Workers, where they don't have dynamic imports, they will always be inlined regardless of this option.

This option will be ignored when `icon.serverBundle.remote` is enabled.

## Completely Disable Server Bundle

If you want to disable the server bundle completely, you can set `icon.serverBundle` to `false` and `provider` to `iconify`

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    provider: 'iconify',
    serverBundle: false,
  },
})
```

This will make requests to Iconify API every time the client requests an icon. We do not recommend doing so unless the other options are not feasible.

## Separate Server and Client Providers

`provider` can also be set separately for SSR and for the browser.

```ts
export default defineNuxtConfig({
  modules: [
    '@nuxt/icon'
  ],
  icon: {
    // SSR uses the server bundle through the local endpoint, the browser fetches from the Iconify API directly
    provider: { server: 'server', client: 'iconify' },
    iconifyApiEndpoint: 'https://icons.example.com',
    serverBundle: {
      collections: ['ph', 'lucide'],
    },
  },
})
```

- A string `provider: X` is the same as `{ server: X, client: X }`.
- The local endpoint is enabled when at least one side uses `server`, and so is the server bundle unless `serverBundle` is `false`. This is decided at build time, so overriding `provider` in `app.config.ts` does not enable or disable them.
- `provider` in `app.config.ts` is not validated: set both `server` and `client` there too. A side left out is taken from the module options when they also use the object form; otherwise it is treated as unset and falls back to the `iconify` provider.
- Unless both sides use `server`, `clientBundle.includeCustomCollections` defaults to `true`, since the client bundle is also used during SSR.


## Sitemap

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