feat: support for external collection packages (#342)

* feat: custom external collection packages * chore: update readme section * chore: include an example in vite-vue3 * chore: include using resolvers fro auto-import * chore: update readme
unplugin · Jan 26, 2024 · dbe23c6 · dbe23c6
1 parent badb1d5
commit dbe23c6
Show file tree

Hide file tree

Showing 7 changed files with 104 additions and 123 deletions.
diff --git a/README.md b/README.md
@@ -735,6 +735,50 @@ IconResolver({
 
 See the [Vue 3 + Vite example](./examples/vite-vue3/vite.config.ts).
 
+### Use Custom External Collection Packages
+
+From version `v0.18.3` you can use other packages to load icons from others authors.
+
+**WARNING**: external packages must include `icons.json` file with the `icons` data in `IconifyJSON` format, which can be exported with Iconify Tools. Check [Exporting icon set as JSON package](https://iconify.design/docs/libraries/tools/export/json-package.html) for more details.
+
+For example, you can use `an-awesome-collection` or `@my-awesome-collections/some-collection` to load your custom or third party icons:
+```ts
+// loader helpers
+import { ExternalPackageIconLoader } from 'unplugin-icons/loaders'
+
+Icons({ customCollections: ExternalPackageIconLoader('my-awesome-collection') })
+```
+
+When using with resolvers for auto-importing, remember you will need to tell it your custom collection names:
+```ts
+IconResolver({
+ customCollections: [
+ 'my-awesome-collection',
+ ],
+})
+```
+
+
+You can also combine it with `FileSystemIconLoader` or with other custom icon loaders:
+```ts
+// loader helpers
+import { ExternalPackageIconLoader, FileSystemIconLoader } from 'unplugin-icons/loaders'
+
+Icons({ 
+ customCollections: {
+ ...ExternalPackageIconLoader('an-awesome-collection'),
+ ...ExternalPackageIconLoader('@my-awesome-collections/some-collection'),
+ ...ExternalPackageIconLoader('@my-awesome-collections/some-other-collection'),
+ 'my-yet-other-icons': FileSystemIconLoader(
+ './assets/icons', 
+ svg => svg.replace(/^<svg /, '<svg fill="currentColor" '),
+ ),
+ },
+)
+```
+
+See the [Vue 3 + Vite example](./examples/vite-vue3/vite.config.ts).
+
 ## Icon customizer
 
 From `v0.13` you can also customize each icon using `iconCustomizer` configuration option or using query params when importing them.

diff --git a/examples/vite-vue3/App.vue b/examples/vite-vue3/App.vue
@@ -5,6 +5,9 @@ import MdiAlarmOff2 from 'virtual:icons/mdi/alarm-off?width=1em&height=1em'
 import RawMdiAlarmOff from 'virtual:icons/mdi/alarm-off?raw&width=4.25rem&height=4.25rem'
 import RawMdiAlarmOff2 from 'virtual:icons/mdi/alarm-off?raw&width=1em&height=1em'
 import RawMdiAlarmOff3 from 'virtual:icons/mdi/alarm-off?raw&width=unset&height=unset'
+import Custom1 from 'virtual:icons/plain-color-icons/about?raw'
+import Custom2 from 'virtual:icons/test-color-icons/about?raw'
+import ExternalCustom3 from 'virtual:icons/test-color-icons/about'
 </script>
 
 <template>
@@ -27,6 +30,9 @@ import RawMdiAlarmOff3 from 'virtual:icons/mdi/alarm-off?raw&width=unset&height=
  <i-twemoji-1st-place-medal />
  <IIcTwotone23mp />
  <MdiStore24Hour />
+ <ExternalCustom3 />
+ <i-test-color-icons:about />
+ <i-plain-color-icons:about />
  <br>
  </p>
  <h2>Customizer via Config</h2>
@@ -80,6 +86,18 @@ import RawMdiAlarmOff3 from 'virtual:icons/mdi/alarm-off?raw&width=unset&height=
  'virtual:icons/mdi/alarm-off?raw&width=unset&height=unset'</code>
  <pre>{{ RawMdiAlarmOff3 }}</pre>
  </div>
+ <span v-html="Custom1" />
+ <div>
+ <code style="opacity: 0.5">import Custom1 from
+ 'virtual:icons/plain-color-icons/about?raw'</code>
+ <pre>{{ Custom1 }}</pre>
+ </div>
+ <span v-html="Custom2" />
+ <div>
+ <code style="opacity: 0.5">import Custom2 from
+ 'virtual:icons/test-color-icons/about?raw'</code>
+ <pre>{{ Custom2 }}</pre>
+ </div>
  </div>
  <br>
  </div>

diff --git a/examples/vite-vue3/components.d.ts b/examples/vite-vue3/components.d.ts
@@ -26,7 +26,9 @@ declare module 'vue' {
  IMdiLightAlarm: typeof import('~icons/mdi-light/alarm')['default']
  INotoV1FlagForFlagJapan: typeof import('~icons/noto-v1/flag-for-flag-japan')['default']
  IParkAbnormal: typeof import('~icons/icon-park/abnormal')['default']
+ 'IPlainColorIcons:about': typeof import('~icons/plain-color-icons/about')['default']
  IRiApps2Line: typeof import('~icons/ri/apps2-line')['default']
+ 'ITestColorIcons:about': typeof import('~icons/test-color-icons/about')['default']
  ITwemoji1stPlaceMedal: typeof import('~icons/twemoji/1st-place-medal')['default']
  }
 }
diff --git a/examples/vite-vue3/vite.config.ts b/examples/vite-vue3/vite.config.ts
@@ -1,17 +1,33 @@
-import { promises as fs } from 'node:fs'
+import { cpSync, promises as fs } from 'node:fs'
 import type { UserConfig } from 'vite'
 import Vue from '@vitejs/plugin-vue'
 import Icons from 'unplugin-icons/vite'
-import { FileSystemIconLoader } from 'unplugin-icons/loaders'
+import { ExternalPackageIconLoader, FileSystemIconLoader } from 'unplugin-icons/loaders'
 import IconsResolver from 'unplugin-icons/resolver'
 import Components from 'unplugin-vue-components/vite'
 
+/************************************************************/
+// DON'T DO THIS IN YOUR CODE: IT IS FOR TESTING PURPOSES ONLY
+cpSync(
+ './plain-color-icons',
+ './node_modules/plain-color-icons',
+ { recursive: true },
+)
+cpSync(
+ './@test-scope',
+ './node_modules/@test-scope',
+ { recursive: true },
+)
+/************************************************************/
+
 const config: UserConfig = {
  plugins: [
  Vue(),
  Icons({
  compiler: 'vue3',
  customCollections: {
+ ...ExternalPackageIconLoader('@test-scope/test-color-icons'),
+ ...ExternalPackageIconLoader('plain-color-icons'),
  custom: FileSystemIconLoader('assets/custom-a'),
  inline: {
  foo: `
@@ -37,7 +53,13 @@ const config: UserConfig = {
  alias: {
  park: 'icon-park',
  },
- customCollections: ['custom', 'inline'],
+ customCollections: [
+ 'custom',
+ 'inline',
+ // custom external packages
+ 'plain-color-icons',
+ 'test-color-icons',
+ ],
  }),
  ],
  }),

diff --git a/package.json b/package.json
@@ -194,7 +194,7 @@
  "dependencies": {
  "@antfu/install-pkg": "^0.3.0",
  "@antfu/utils": "^0.7.6",
- "@iconify/utils": "^2.1.12",
+ "@iconify/utils": "^2.1.20",
  "debug": "^4.3.4",
  "kolorist": "^1.8.0",
  "local-pkg": "^0.5.0",