vuepress-theme-plume/docs/en/guide/quick-start/optimize-build.md

title, icon, outline, createTime, permalink

title	icon	outline	createTime	permalink
Build Optimization	clarity:bundle-solid	2	2025/10/08 01:50:20	/en/guide/optimize-build/

Image Dimension Optimization

When embedding images in Markdown documents via ![alt](url) 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, 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:

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 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:

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.