feat: ✨ add interface for accessing ionic icons (#27)

Author: Lexpeartha

docs/content/2.getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: Getting started
-description: ''
+description: 'Download & install Ionic and setup Capacitor for usage'
 ---
 
 ## Installation
@@ -96,6 +96,11 @@ export default defineNuxtConfig({
   Default: `true`
   Disable to configure Ionic Router yourself.
 
+- **icons**
+
+  Default: `true`
+  Disable to stop icons from being auto-imported.
+
 ### `css`
 
 - **core**

docs/content/3.usage.md renamed to docs/content/3.features.md

@@ -1,11 +1,11 @@
 ---
-title: Usage
-description: ''
+title: Features
+description: 'All the features this module offers for building apps with Ionic at great speed'
 ---
 
 ## Page routing
 
-Out of the box, you can start building your Ionic application by creating routes within `~/pages` directory. To access the router, you should use `useIonRouter()` rather than an import from `vue-router`.
+Out of the box, you can start building your Ionic application by creating routes within `~/pages` directory. To access the router, you should use `useIonRouter()` rather than `useRouter()` (which is auto-imported from `vue-router`).
 
 Nuxt utilities like `definePageMeta` will continue to work, but you should avoid using `<NuxtPage>` or `<NuxtLayout>`.
 
@@ -30,6 +30,34 @@ All Ionic Vue components should be auto-imported throughout your app. (If you fi
 
 For more on how component imports work, see the [Nuxt documentation](https://v3.nuxtjs.org/guide/directory-structure/components#components-directory).
 
+## Icons
+
+Icons are auto-imported from `ionicons/icons` by default, following the pattern of camel case naming with `ionicons` in front of the original icon name from the [official icons website](https://ionic.io/ionicons).
+
+For example, instead of this
+
+```vue [component.vue]
+<script setup lang="ts">
+import { image, squareSharp, triangleOutline } from 'ionicons/icons'
+</script>
+
+<template>
+  <ion-icon :icon="image"></ion-icon>
+  <ion-icon :md="squareSharp" :ios="triangleOutline"></ion-icon>
+</template>
+```
+
+You would write this
+
+```vue [component.vue]
+<template>
+  <ion-icon :icon="ioniconsImage"></ion-icon>
+  <ion-icon :md="ioniconsSquareSharp" :ios="ioniconsTriangleOutline"></ion-icon>
+</template>
+```
+
+You can opt-out of auto-importing by setting `integrations.icons` module options in your `nuxt.config.ts` to `false`.
+
 ## Helper functions
 
 Nuxt provides a number of Ionic hooks/composables via auto-imports within your app:

playground/nuxt.config.ts

@@ -4,6 +4,7 @@ export default defineNuxtConfig({
   modules: ['nuxt-ionic'],
   ionic: {
     // integrations: {
+    //   icons: true,
     //   meta: true,
     //   pwa: true,
     //   router: true,

playground/pages/tabs.vue

@@ -1,5 +1,4 @@
 <script setup lang="ts">
-import { images, square, triangle } from 'ionicons/icons'
 useHead({
   title: 'Nuxt Ionic',
 })
@@ -12,17 +11,17 @@ useHead({
         <ion-router-outlet />
         <ion-tab-bar slot="bottom">
           <ion-tab-button tab="tab1" href="/tabs/tab1">
-            <ion-icon :icon="triangle" />
+            <ion-icon :icon="ioniconsHomeOutline" />
             <ion-label>Tab 1</ion-label>
           </ion-tab-button>
 
           <ion-tab-button tab="tab2" href="/tabs/tab2">
-            <ion-icon :icon="images" />
+            <ion-icon :icon="ioniconsImagesOutline" />
             <ion-label>Photos</ion-label>
           </ion-tab-button>
 
           <ion-tab-button tab="tab3" href="/tabs/tab3">
-            <ion-icon :icon="square" />
+            <ion-icon :icon="ioniconsBulbOutline" />
             <ion-label>Tab 3</ion-label>
           </ion-tab-button>
         </ion-tab-bar>

src/module.ts

@@ -8,6 +8,7 @@ import { defineUnimportPreset } from 'unimport'
 import { runtimeDir } from './utils'
 
 import { useCSSSetup } from './parts/css'
+import { setupIcons } from './parts/icons'
 import { setupMeta } from './parts/meta'
 import { setupPWA } from './parts/pwa'
 import { setupRouter } from './parts/router'
@@ -17,6 +18,7 @@ export interface ModuleOptions {
     router?: boolean
     pwa?: boolean
     meta?: boolean
+    icons?: boolean
   }
   css?: {
     core?: boolean
@@ -35,6 +37,7 @@ export default defineNuxtModule<ModuleOptions>({
       meta: true,
       pwa: true,
       router: true,
+      icons: true,
     },
     css: {
       core: true,
@@ -102,6 +105,11 @@ export default defineNuxtModule<ModuleOptions>({
       await setupUtilities()
     }
 
+    // Add auto-imported icons
+    if (options.integrations?.icons) {
+      await setupIcons()
+    }
+
     if (options.integrations?.meta) {
       await setupMeta()
     }

src/parts/icons.ts

@@ -0,0 +1,20 @@
+import { useNuxt } from '@nuxt/kit'
+import { defineUnimportPreset } from 'unimport'
+import * as icons from 'ionicons/icons'
+
+const iconsPreset = defineUnimportPreset({
+  from: 'ionicons/icons',
+  // @ts-ignore-next-line
+  imports: Object.keys(icons.default || icons).map(name => ({
+    name,
+    as: 'ionicons' + name[0].toUpperCase() + name.slice(1),
+  })),
+})
+
+export const setupIcons = () => {
+  const nuxt = useNuxt()
+
+  nuxt.hook('autoImports:sources', presets => {
+    presets.push(iconsPreset)
+  })
+}