Exporting icon set as icon package

This tutorial is part of export functions documentation in Iconify Tools.

Function exportIconPackage() creates icon package in specified directory.

These packages are used in offline icon components, like this:

jsximport { Icon, addIcon/* , addCollection */ } from '@iconify/react/dist/offline';
import bellFill from '@iconify-icons/bi/bell-fill';

// Assign icon data to name "bell" used in first example
addIcon('bell', bellFill);

// Test component
export function iconDemo() {
   return (
       <div>
           <div>
               Icon referenced by name: <Icon icon="bell" />
           </div>
           <div>
               Icon referenced by object: <Icon icon={bellFill} />
           </div>
       </div>
   );
}

@iconify-icons/bi is a package generated by this function, used in example above.

See split icon packages documentation for details.

Deprecation notice

This function is deprecated, but it is still maintained for developers that do rely on it.

Single icon packages were needed in the early stages of Iconify project. In the modern Node ecosystem, this is no longer needed. Tools like Vite can be used to generate content on demand, including single file packages. Packages like Unplugin Icons dynamically generate icon components.

Single icon packages are no longer needed and should be avoided. If you need to extract data for few icons, do it during the build process of your app as either a custom script or a Vite plugin.

Usage

Function has the following parameters:

• iconSet, IconSet. Icon set to export.
• options, object. Options. See below.

Function returns array of generated files.

Function is asynchronous. That means you need to handle it as Promise instance, usually by adding await before function call.

Options

The options object has the following mandatory property:

• target, string. Target directory. If a directory is missing, it will be created.

and the following optional properties:

• cleanup, boolean. If true, target directory will be emptied before exporting icons. Default is false.
• package, object. Properties for package.json. Use this to set at least package name and version.
• module, boolean. If true, function generates package with ES modules, if false, function generates package with CommonJS modules. Default is true.
• typesContent, string. Custom content of .d.ts files.
• customFiles, Record<string,unknown>. Custom files to export. Key is filename, value is content. See below.

customFiles

customFiles option contains additional files you want to add to package. Key is filename, value can be one of these types:

• string. Content of file.
• object. JSON content that will be serialized before writing file.
• null. If value is null, file is deleted.

Example

example.ts

tsimport { exportIconPackage, IconSet/* , execAsync */ } from '@iconify/tools';

// Import icon set
const iconSet = new IconSet({
   prefix: 'carbon',
   icons: {
       'add': {
           body: '<path d="M17 15V8h-2v7H8v2h7v7h2v-7h7v-2z" fill="currentColor"/>',
       },
       'arrow-down-regular': {
           body: '<path d="M24.59 16.59L17 24.17V4h-2v20.17l-7.59-7.58L6 18l10 10l10-10l-1.41-1.41z" fill="currentColor"/>',
       },
       'arrow-left-regular': {
           body: '<path d="M14 26l1.41-1.41L7.83 17H28v-2H7.83l7.58-7.59L14 6L4 16l10 10z" fill="currentColor"/>',
       },
       'back-to-top-regular': {
           body: '<path d="M16 14L6 24l1.4 1.4l8.6-8.6l8.6 8.6L26 24z" fill="currentColor"/><path d="M4 8h24v2H4z" fill="currentColor"/>',
       },
       'bookmark-filled': {
           body: '<path d="M24 2H8a2 2 0 0 0-2 2v26l10-5.054L26 30V4a2 2 0 0 0-2-2z" fill="currentColor"/>',
       },
       'caret-down-regular': {
           body: '<path d="M24 12l-8 10l-8-10z" fill="currentColor"/>',
       },
       'caret-left-regular': {
           body: '<path d="M20 24l-10-8l10-8z" fill="currentColor"/>',
       },
   },
   aliases: {
       'add-regular': {
           parent: 'add',
       },
       'arrow-up-regular': {
           parent: 'arrow-down-regular',
           vFlip: true,
       },
       'arrow-right-regular': {
           parent: 'arrow-left-regular',
           hFlip: true,
       },
       'caret-up-regular': {
           parent: 'caret-down-regular',
           vFlip: true,
       },
       'caret-right-regular': {
           parent: 'caret-left-regular',
           hFlip: true,
       },
   },
   width: 32,
   height: 32,
});

(async () => {
   // Target directory
   const target = `output/${iconSet.prefix}`;

   // Export package
   await exportIconPackage(iconSet, {
       target,
       module: true,
       package: {
           name: `@iconify-icons/${iconSet.prefix}`,
           version: '1.0.0',
           bugs: 'https://github.com/iconify/iconify/issues',
           homepage: 'https://github.com/iconify/iconify',
       },
       cleanup: true,
       /*
       customFiles: {
           'README.md': 'README!',
       },
       */
   });

   // Publish NPM package
   /*
   await execAsync('npm publish --access=public --silent', {
       cwd: target,
   });
   */
})();