Deployment & SSR bundles

Astro Iconset works with any Astro deployment target. This page covers how rendering mode affects icon resolution and how to keep server bundles small.

Rendering modes

Astro supports three rendering modes. Here is how Astro Iconset behaves in each:

Mode	How icons are resolved	Bundle concern
Static (output: 'static')	All icons resolved at build time, embedded in HTML	None — no server bundle
Hybrid (output: 'hybrid')	Pre-rendered routes resolved at build time; server routes resolved at request time	Only server routes need include
Server (output: 'server')	All icons resolved at request time from Iconify data in server bundle	Configure include to avoid shipping entire sets

Static sites (no action needed)

For a fully static Astro site, icon resolution happens at build time. Every <Icon> becomes an SVG in your HTML output. No include configuration is needed.

npm

npm run build

pnpm

pnpm build

Yarn

yarn build

The dist/ folder contains everything — no server JavaScript involved.

Server and hybrid output

When using an SSR adapter, Iconify icon data from @iconify-json/* packages is included in the server JavaScript bundle by default. If you install large sets (e.g. @iconify-json/mdi with ~7,000 icons), all of them are bundled unless you restrict them with include.

Install an adapter

npm

# Vercel
npm install @astrojs/vercel

# Netlify
npm install @astrojs/netlify

# Node.js server
npm install @astrojs/node

pnpm

pnpm add @astrojs/vercel
pnpm add @astrojs/netlify
pnpm add @astrojs/node

Yarn

yarn add @astrojs/vercel
yarn add @astrojs/netlify
yarn add @astrojs/node

Full server output (output: 'server')

All routes are server-rendered. Use include to limit which Iconify icons ship in the bundle:

astro.config.mjs

import { defineConfig } from "astro/config";
import vercel from "@astrojs/vercel/serverless";
import icon from "astro-iconset";

export default defineConfig({
  output: "server",
  adapter: vercel(),
  integrations: [
    icon({
      include: {
        // Only ship the icons your server routes actually render
        mdi: ["account", "home", "menu", "close"],
        // To include a whole set (can be large):
        // ri: ["*"],
      },
    }),
  ],
});

Caution

Without include, all icons from every installed @iconify-json/* package are included in the server bundle. For large sets this can add megabytes of JSON to your deployed function.

Hybrid output (output: 'hybrid')

Pre-rendered (static) routes resolve icons at build time. Only server-rendered routes need icons bundled. Configure include for the icons used on those routes:

astro.config.mjs

import { defineConfig } from "astro/config";
import node from "@astrojs/node";
import icon from "astro-iconset";

export default defineConfig({
  output: "hybrid",
  adapter: node({ mode: "standalone" }),
  integrations: [
    icon({
      include: {
        mdi: ["account", "logout"],
      },
    }),
  ],
});

Pages that use export const prerender = true are built statically — their icons do not need to be in include. Only the dynamic (non-prerendered) routes need it.

Icons work in dev but are missing in production

The dev server resolves Iconify icons on demand from disk. The production server only serves what was bundled at build time via include. If an icon appears in dev but disappears in production, add it to the include map.

astro.config.mjs

icon({
  include: {
   mdi: ["account"],
   mdi: ["account", "settings"],  // add the missing icon
  },
}),

Related

• include configuration option — full option reference
• Local & Iconify icons — installing sets and referencing set:icon
• Troubleshooting — common SSR bundle problems