116 lines
4.1 KiB
Markdown
116 lines
4.1 KiB
Markdown
---
|
|
title: Build Optimization
|
|
icon: clarity:bundle-solid
|
|
outline: 2
|
|
createTime: 2025/10/08 01:50:20
|
|
permalink: /en/guide/optimize-build/
|
|
---
|
|
|
|
## Image Dimension Optimization <Badge type="warning" text="Experimental" />
|
|
|
|
When embedding images in Markdown documents via `` or `<img src="url">`,
|
|
the content displays correctly, but potential layout stability issues are often overlooked.
|
|
|
|
### Layout Shift Analysis
|
|
|
|
Layout shifts are not obvious when images are small or network conditions are good.
|
|
However, with large images or poor network conditions, layout reflow during image loading becomes prominent:
|
|
|
|
1. **Before Loading**: Image placeholder space is not reserved, subsequent content is pushed up
|
|
2. **After Loading**: Image suddenly occupies space, forcing subsequent content to reflow
|
|
3. **User Experience**: Frequent layout changes cause visual jumps and operation lag
|
|
|
|
### Solution: Pre-calculate Image Dimensions
|
|
|
|
According to [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#height),
|
|
specifying both `height` and `width` attributes allows browsers to calculate the image aspect
|
|
ratio in advance and reserve display space, eliminating layout shifts at the source.
|
|
|
|
Automated solution provided by the theme:
|
|
|
|
```ts
|
|
export default defineUserConfig({
|
|
theme: plumeTheme({
|
|
plugins: {
|
|
markdownPower: {
|
|
imageSize: true, // Optional 'local' | 'all'
|
|
},
|
|
}
|
|
})
|
|
})
|
|
```
|
|
|
|
**Configuration Options**:
|
|
|
|
- `'local'` or `true`: Only add dimension attributes for local images
|
|
- `'all'`: Process both local and remote image resources
|
|
|
|
**Implementation Mechanism**:
|
|
|
|
- Automatically analyze original image dimensions during build
|
|
- Inject precise `width` and `height` attributes into `<img>` tags
|
|
- Reserve display space based on image aspect ratio
|
|
|
|
::: important Performance Considerations
|
|
|
|
- This feature only takes effect in **production builds** to avoid performance overhead during development
|
|
- Using the `'all'` option requests all remote image resources, which may significantly increase build time
|
|
- Optimization strategy: Concurrent requests + header information analysis, terminating connections immediately after obtaining dimension data
|
|
:::
|
|
|
|
## Icon Loading Optimization
|
|
|
|
### Iconify Integration Benefits
|
|
|
|
The theme deeply integrates with the [Iconify](https://icon-sets.iconify.design/) project,
|
|
providing access to over 200,000 icons with flexible selection. Although locally installing the
|
|
`@iconify/json` package requires approximately 70MB of storage,
|
|
only the actually used icon resources are included in the build, achieving on-demand loading.
|
|
|
|
### Performance Bottlenecks and Solutions
|
|
|
|
**Root Cause**:
|
|
Icons are organized by collections, with each collection containing JSON files of 100-1000+ icons.
|
|
When using icons from multiple different collections, frequent I/O reads and JSON parsing create significant performance overhead.
|
|
|
|
**Real-world Case**:
|
|
|
|
- Using 160+ icons from 54 icon collections
|
|
- Initial build: ~500ms icon parsing time
|
|
- User experience: Slow development server startup
|
|
|
|
**Cache Optimization Mechanism**:
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[First Build] --> B[Parse Used Icons]
|
|
B --> C[Generate Cache File]
|
|
C --> D[Subsequent Builds]
|
|
D --> E[Read Cache]
|
|
E --> F[20ms Loading Time]
|
|
```
|
|
|
|
**Optimization Results**:
|
|
|
|
- Build time reduced from 500ms to 20ms
|
|
- Development server startup speed significantly improved
|
|
- Maximum resource utilization
|
|
|
|
### Best Practice Recommendations
|
|
|
|
1. **Icon Usage Planning**:
|
|
- Prioritize icons from the same collection
|
|
- Avoid overly dispersed usage across different collections
|
|
|
|
2. **Development Experience Optimization**:
|
|
- Cache automatically takes effect after first startup
|
|
- Intelligent cache updates when adding new icons
|
|
- No manual cache management required
|
|
|
|
3. **Production Build Assurance**:
|
|
- Cache mechanism doesn't affect final output
|
|
- Maintains on-demand loading characteristics of icon resources
|
|
- Ensures optimal build artifact size
|
|
|
|
Through these two optimization measures, the theme maintains rich functionality while ensuring excellent build performance and runtime experience.
|