@tomjs/vite-plugin-iconify

December 13, 2025 · View on GitHub

node-current (scoped) NPM

English | 中文

A Vite plugin for handling iconify icon sets in environments without internet access.

Install

# pnpm
pnpm add @tomjs/vite-plugin-iconify -D

# yarn
yarn add @tomjs/vite-plugin-iconify -D

# npm
npm i @tomjs/vite-plugin-iconify --save-dev

Instructions

Install either @iconify/json or @iconify-json/* packages as needed.
The plugin will first check if @iconify/json is installed; otherwise, it will read @iconify-json/* and copy @iconify-json/*/icons.json to @iconify/json/json/*.json.

Usage

Using Vue/React projects as examples:

Using the plugin

Vue Example

import iconify from '@tomjs/vite-plugin-iconify';
import vue from '@vitejs/plugin-vue';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    vue(),
    iconify({
      resources: ['https://unpkg.com/@iconify/json/json'],
      rotate: 3000,
      local: ['ant-design', 'ep'],
      icons: ['ant-design:plus-outlined'] // Optional. If set, the ant-design JSON set will include only the icons specified here. The ep set will remain complete.
    }),
  ],
});

React Example

import iconify from '@tomjs/vite-plugin-iconify';
import react from '@vitejs/plugin-react-swc';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    react(),
    iconify({
      resources: ['https://unpkg.com/@iconify/json/json'],
      rotate: 3000,
      local: ['ant-design', 'ep'],
    }),
  ],
});

Documentation

index.d.ts provided by unpkg.com.

Parameters

Parameter	Type	Default	Description
selector	`string`	'title'	The tag selector to inject the IconifyProviders script after
resources	`string[]`	[]	Icon API URLs, default includes https://api.iconify.design
rotate	`number`	750	Timeout in milliseconds before using the next host
timeout	`number`	5000	Timeout in milliseconds before an API query is considered failed
version	`string`	'latest'	Set the version of `@iconify/json` to use. Default is read from `package.json`, if `@iconify/json` not exists, use `"latest"`
local	`'boolean'\|'IconifySet[]'\|IconifyLocal[]`	false	Local icon set configuration

resources: You can add npm cdn or custom url:

IconifySet

Iconify icon set, refer to icon sets or Icônes

IconifyLocal

By configuring this parameter, the local icon set will be copied to the outDir directory based on the sets configuration.

Parameter	Type	Default	Description
sets	`IconifySet[]`	[]	Iconify icon sets
icons	`${IconifySet}:${string}`	[]	Iconify icons list
base	`string`	'/'	Same as the `base` option in Vite configuration
outDir	`string`	'dist'	Local output directory, default is the same as the `build.outDir` option in Vite configuration
path	`string`	'npm/@iconify/json@{version}'	Local output path, the corresponding module URL will also be replaced with this path

Using CLI

Generate Iconify icon set data for icon selection and other functionalities.

Add the following script to package.json under scripts : ti ant-design ep --path src/constants
Or run the following command directly: pnpm ti ant-design ep --path src/constants

Usage:
  $ ti [...sets]

Commands:
  [...sets]  create icon collection data based on @iconify/json in the project

For more info, run any command with the `--help` flag:
  $ ti --help

Options:
  --path <path>  [string] output file path. (default: src)
  --name <name>  [string] output file name. if tsconfig is exists, default is 'iconify.ts', or is 'iconify.js'
  --type <type>  ["esm" | "cjs"] output file type. (default: esm)
  -h, --help     Display this message
  -v, --version  Display version number

Development

Development requirements:
- git
- node>=16
- pnpm>=8
For the first time, install dependencies by running the following command:

# Install dependencies
pnpm i
# build library
pnpm build

To debug the vue project, execute the following commands:

cd examples/vue
pnpm build
pnpm preview

To debug the react project, execute the following commands:

cd examples/react
pnpm build
pnpm preview