0
# Progressive Loading
1

2
Progressive image loading functionality that generates low-resolution placeholders for Vuetify image components, providing smooth loading experiences and perceived performance improvements.
3

4
## Capabilities
5

6
### VuetifyProgressiveModule
7

8
Vue template compiler module that transforms image source attributes to enable progressive loading.
9

10
```javascript { .api }
11
/**
12
 * Vue compiler module for progressive image loading
13
 * Transforms v-img, v-card-media, and v-carousel-item components
14
 */
15
const VuetifyProgressiveModule = {
16
  /** Post-transform function for Vue template compilation */
17
  postTransformNode: Function
18
};
19

20
/**
21
 * Transform function for image components
22
 * @param {VNode} node - Vue template node
23
 * @returns {VNode} - Transformed node with progressive loading
24
 */
25
function postTransformNode(node);
26
```
27

28
**Usage Example:**
29

30
```javascript
31
// webpack.config.js
32
const { VuetifyProgressiveModule } = require('vuetify-loader');
33

34
module.exports = {
35
  module: {
36
    rules: [
37
      {
38
        test: /\.vue$/,
39
        loader: 'vue-loader',
40
        options: {
41
          compilerOptions: {
42
            modules: [VuetifyProgressiveModule]
43
          }
44
        }
45
      }
46
    ]
47
  }
48
};
49
```
50

51
### Progressive Loader Function
52

53
Webpack loader that processes image files and generates low-resolution placeholders.
54

55
```javascript { .api }
56
/**
57
 * Webpack loader for generating progressive image placeholders
58
 * @param {Buffer} contentBuffer - Image file buffer
59
 * @returns {void} - Calls callback with processed result
60
 */
61
function progressiveLoader(contentBuffer);
62

63
// Loader properties
64
progressiveLoader.raw = true; // Handles binary data
65
```
66

67
**Webpack Rule Configuration:**
68

69
```javascript
70
module.exports = {
71
  module: {
72
    rules: [
73
      {
74
        test: /\.(png|jpe?g|gif)$/,
75
        resourceQuery: /vuetify-preload/,
76
        use: [
77
          {
78
            loader: 'vuetify-loader/progressive-loader',
79
            options: {
80
              size: 9,                    // Preview size in pixels
81
              sharp: false,               // Use sharp library
82
              graphicsMagick: false       // Use GraphicsMagick
83
            }
84
          },
85
          {
86
            loader: 'url-loader',
87
            options: { limit: 8000 }
88
          }
89
        ]
90
      }
91
    ]
92
  }
93
};
94
```
95

96
### Configuration Options
97

98
Options for controlling progressive image generation behavior.
99

100
```javascript { .api }
101
interface ProgressiveLoaderOptions {
102
  /**
103
   * Minimum dimensions of preview images in pixels
104
   * @default 9
105
   */
106
  size?: number;
107
  
108
  /**
109
   * Use sharp library instead of GraphicsMagick
110
   * Better for environments without ImageMagick
111
   * @default false
112
   */
113
  sharp?: boolean;
114
  
115
  /**
116
   * Use GraphicsMagick instead of ImageMagick
117
   * @default false
118
   */
119
  graphicsMagick?: boolean;
120
}
121
```
122

123
### Image Processing Workflow
124

125
The progressive loader follows this process:
126

127
1. **Input Detection**: Determines if content is already a data URL or file export
128
2. **Library Selection**: Uses either Sharp or GraphicsMagick based on configuration
129
3. **Placeholder Generation**: Creates low-resolution version of the image
130
4. **Aspect Ratio Calculation**: Preserves original image proportions
131
5. **Output Creation**: Generates module with both original source and lazy placeholder
132

133
### Generated Output Format
134

135
The loader produces modules with both original and placeholder data:
136

137
```javascript { .api }
138
// Generated module structure
139
interface ProgressiveImageModule {
140
  /** Original image source (URL or data URI) */
141
  src: string;
142
  /** Low-resolution placeholder as data URI */
143
  lazySrc: string;
144
  /** Aspect ratio (width/height) for layout */
145
  aspect: number;
146
}
147
```
148

149
**Example Usage in Templates:**
150

151
```vue
152
<template>
153
  <!-- Automatic transformation by VuetifyProgressiveModule -->
154
  <v-img src="@/assets/hero-image.jpg"></v-img>
155
  
156
  <!-- Manual progressive loading -->
157
  <v-img :src="require('@/assets/product.jpg?vuetify-preload')"></v-img>
158
  
159
  <!-- Selective lazy loading -->
160
  <v-img src="@/assets/background.jpg?lazy"></v-img>
161
</template>
162
```
163

164
## Advanced Usage Patterns
165

166
### Combining with URL Loader
167

168
Use `Rule.oneOf` to prevent conflicts with other image loaders:
169

170
```javascript
171
{
172
  test: /\.(png|jpe?g|gif|svg|eot|ttf|woff|woff2)(\?.*)?$/,
173
  oneOf: [
174
    {
175
      test: /\.(png|jpe?g|gif)$/,
176
      resourceQuery: /vuetify-preload/,
177
      use: [
178
        'vuetify-loader/progressive-loader',
179
        {
180
          loader: 'url-loader',
181
          options: { limit: 8000 }
182
        }
183
      ]
184
    },
185
    {
186
      loader: 'url-loader',
187
      options: { limit: 8000 }
188
    }
189
  ]
190
}
191
```
192

193
### Dynamic Image Loading
194

195
For dynamic paths or loops, manual require statements are needed:
196

197
```vue
198
<template>
199
  <!-- Dynamic images in loops -->
200
  <v-img 
201
    v-for="i in imageCount" 
202
    :key="i"
203
    :src="require(`@/images/gallery-${i}.jpg?vuetify-preload`)"
204
  ></v-img>
205
  
206
  <!-- Conditional progressive loading -->
207
  <v-img 
208
    :src="lazy ? require(`@/assets/${image}?vuetify-preload`) : require(`@/assets/${image}`)"
209
  ></v-img>
210
</template>
211
```
212

213
### Selective Progressive Loading
214

215
Apply progressive loading only to specific images using query parameters:
216

217
```javascript
218
// Webpack rule for selective loading
219
{
220
  test: /\.(png|jpe?g|gif)$/,
221
  resourceQuery: /lazy\?vuetify-preload/,
222
  use: ['vuetify-loader/progressive-loader']
223
}
224
```
225

226
```vue
227
<template>
228
  <!-- Only images with ?lazy will get progressive loading -->
229
  <v-img src="@/assets/hero.jpg?lazy"></v-img>
230
  <v-img src="@/assets/icon.jpg"></v-img> <!-- No progressive loading -->
231
</template>
232
```
233

234
## Dependencies and Requirements
235

236
### System Requirements
237

238
- **ImageMagick or GraphicsMagick**: Required for image processing (unless using Sharp)
239
- **Sharp** (optional): Alternative image processing library for environments without ImageMagick
240

241
### npm Dependencies
242

243
```javascript
244
// Required dependencies
245
"gm": "^1.23.1"           // GraphicsMagick/ImageMagick bindings
246
"loader-utils": "^1.1.0"  // Webpack loader utilities
247

248
// Optional dependencies
249
"sharp": "^0.x.x"         // Alternative image processing
250
```
251

252
### Supported Image Components
253

254
The progressive module automatically transforms these Vuetify components:
255

256
- `v-img`: Primary image component
257
- `v-card-media`: Deprecated card media component  
258
- `v-carousel-item`: Carousel slide images
259

260
## Error Handling
261

262
### Image Processing Errors
263

264
- **Missing ImageMagick**: Logged to console, does not break build
265
- **Invalid image format**: Gracefully handled with error logging
266
- **File system errors**: Logged but build continues
267

268
### Configuration Errors
269

270
- **Invalid options**: Uses default values for missing or invalid options
271
- **Missing loader configuration**: Falls back to standard file processing
272

273
**Error Logging Example:**
274

275
```javascript
276
// Errors are logged to console but don't break the build
277
gm(path).size(function(err, info) {
278
  if (err) console.error(err);
279
  // Process continues with error handling
280
});
281
```