0
# Icon Generation
1

2
Automatic icon generation and resizing functionality that creates multiple icon sizes from a source image for various device requirements and iOS splash screens.
3

4
## Capabilities
5

6
### Icon Generation Function
7

8
Handles the complete icon generation pipeline from source image to generated assets.
9

10
```typescript { .api }
11
/**
12
 * Main icon generation function
13
 * @param nuxt - Nuxt instance
14
 * @param pwa - PWA context containing configuration
15
 * @param moduleContainer - Nuxt module container for plugins
16
 */
17
async function icon(nuxt: any, pwa: PWAContext, moduleContainer: any): Promise<void>;
18

19
interface IconOptions {
20
  /** Path to source icon image */
21
  source: string;
22
  /** Default filename to search for icon */
23
  fileName: string;
24
  /** Array of sizes to generate (square icons) */
25
  sizes: number[];
26
  /** iOS splash screen sizes with device types */
27
  iosSizes: iOSSize[];
28
  /** Directory for generated icons */
29
  targetDir: string;
30
  /** Enable runtime icon plugin */
31
  plugin: boolean;
32
  /** Name of the injected icon plugin */
33
  pluginName: string;
34
  /** Icon purpose for manifest (any, maskable, badge) */
35
  purpose: string[] | string;
36
  /** Cache directory for processed icons */
37
  cacheDir: string;
38
  /** Public path for icon URLs */
39
  publicPath: string;
40
}
41

42
type iOSSize = [number, number, iOSType];
43
type iOSType = 'ipad' | 'ipadpro9' | 'ipadpro10' | 'ipadpro12' | 'iphonese' | 'iphone6' | 'iphoneplus' | 'iphonex' | 'iphonexr' | 'iphonexsmax';
44
```
45

46
**Usage Example:**
47

48
```typescript
49
// nuxt.config.ts
50
export default {
51
  pwa: {
52
    icon: {
53
      source: 'static/app-icon.png',
54
      sizes: [64, 120, 144, 152, 192, 384, 512],
55
      purpose: ['any', 'maskable'],
56
      targetDir: 'icons'
57
    }
58
  }
59
}
60
```
61

62
### Icon Discovery
63

64
Automatically locates source icon files from multiple potential locations.
65

66
```typescript { .api }
67
/**
68
 * Find icon source file from various locations
69
 * @param nuxt - Nuxt instance
70
 * @param options - Icon options containing potential sources
71
 * @returns Path to found icon or undefined
72
 */
73
function findIcon(nuxt: any, options: IconOptions): Promise<string | undefined>;
74
```
75

76
The function searches in this order:
77
1. Explicitly configured `source` path
78
2. `[srcDir]/[staticDir]/[fileName]` (e.g., `static/icon.png`)
79
3. `[srcDir]/[assetsDir]/[fileName]` (e.g., `assets/icon.png`)
80

81
### Icon Generation Process
82

83
Generates multiple icon sizes using image processing.
84

85
```typescript { .api }
86
/**
87
 * Generate all required icon sizes from source
88
 * @param nuxt - Nuxt instance  
89
 * @param options - Icon options with sizes and configuration
90
 */
91
function generateIcons(nuxt: any, options: IconOptions): Promise<void>;
92
```
93

94
The process:
95
1. Calculates hash of source image for cache invalidation
96
2. Creates icon assets for each specified size
97
3. Generates iOS splash screens for different device types
98
4. Updates manifest with generated icon references
99

100
### Runtime Icon Plugin
101

102
Provides runtime access to generated icons through Vue plugin injection.
103

104
```typescript { .api }
105
/**
106
 * Add Vue plugin for runtime icon access
107
 * @param nuxt - Nuxt instance
108
 * @param options - Icon options with generated assets
109
 * @param moduleContainer - Nuxt module container for plugin registration
110
 */
111
function addPlugin(nuxt: any, options: IconOptions, moduleContainer: any): void;
112

113
/**
114
 * Icon plugin injected into Vue context
115
 * @param size - Icon size as string (e.g., '192x192')
116
 * @returns URL to the generated icon of specified size
117
 */
118
interface IconPlugin {
119
  (size: string): string;
120
}
121
```
122

123
**Usage Example:**
124

125
```typescript
126
// In Vue components
127
export default {
128
  mounted() {
129
    // Access generated icons
130
    const icon192 = this.$icon('192x192');
131
    const icon512 = this.$icon('512x512');
132
    
133
    console.log('Large icon URL:', icon512);
134
  }
135
}
136
```
137

138
### Icon Processing
139

140
Background icon resizing using optimized image processing.
141

142
```typescript { .api }
143
/**
144
 * Resize source icon to multiple target sizes
145
 * @param nuxt - Nuxt instance
146
 * @param options - Icon options with size specifications
147
 */
148
function resizeIcons(nuxt: any, options: IconOptions): Promise<void>;
149
```
150

151
Features:
152
- Uses jimp-compact for efficient image processing
153
- Maintains aspect ratio with contain strategy
154
- Processes in background using child processes
155
- Implements caching to avoid redundant processing
156
- Generates integrity files for cache validation
157

158
### Manifest Integration
159

160
Automatically integrates generated icons into the web app manifest.
161

162
```typescript { .api }
163
/**
164
 * Add generated icons to PWA manifest
165
 * @param nuxt - Nuxt instance
166
 * @param options - Icon options with generated assets
167
 * @param pwa - PWA context for manifest updates
168
 */
169
function addManifest(nuxt: any, options: IconOptions, pwa: PWAContext): void;
170
```
171

172
Creates manifest icon entries:
173
```json
174
{
175
  "icons": [
176
    {
177
      "src": "/icons/icon_64x64.abc123.png",
178
      "sizes": "64x64",
179
      "type": "image/png",
180
      "purpose": "any maskable"
181
    }
182
  ]
183
}
184
```
185

186
### iOS Splash Screen Support
187

188
Generates splash screens for iOS devices with proper media queries.
189

190
Default iOS sizes include:
191
- iPad (1536x2048)
192
- iPad Pro 9.7" (1536x2048)
193
- iPad Pro 10.5" (1668x2224)  
194
- iPad Pro 12.9" (2048x2732)
195
- iPhone SE (640x1136)
196
- iPhone 6/7/8 (750x1334)
197
- iPhone Plus (1080x1920)
198
- iPhone X (1125x2436)
199
- iPhone XR (828x1792)
200
- iPhone XS Max (1242x2688)
201

202
**Note:** The source code contains a typo with an incorrect iPhone 6 width (50 instead of 750), which should be corrected in implementation.
203

204
### Asset Emission
205

206
Manages webpack asset emission for generated icons.
207

208
```typescript { .api }
209
/**
210
 * Emit generated icons as webpack assets
211
 * @param nuxt - Nuxt instance
212
 * @param options - Icon options with asset specifications
213
 */
214
function emitAssets(nuxt: any, options: IconOptions): void;
215
```
216

217
Handles:
218
- Build-time asset emission
219
- Generate-time asset emission for static sites
220
- Lazy asset loading with promise-based resolution
221
- Proper file naming with content hashes