KArtSell.Aegis/frontend/PERFORMANCE_GUIDE.md

Performance Optimization Guide

Overview

This guide outlines performance best practices for the K-ArtSell Aegis frontend application.

1. Code Splitting

Route-Based Code Splitting

All pages are lazy-loaded to reduce initial bundle size:

// router.ts
import { defineAsyncComponent } from 'vue'

const ShadowRunQueue = defineAsyncComponent(() =>
  import('./features/shadow-run/pages/ShadowRunQueue.vue')
)

Dynamic Imports

For large components, use dynamic imports:

const HeavyComponent = defineAsyncComponent(() =>
  import('./components/HeavyComponent.vue')
)

2. Bundle Analysis

Check bundle size:

npm run build -- --report

Current budgets:

• Main bundle: < 200KB (gzipped)
• Vendor bundle: < 300KB (gzipped)
• Per-route chunk: < 50KB (gzipped)

3. Image Optimization

Image Sizes

All images should be optimized before deployment:

# Optimize PNG
optipng -o2 image.png

# Optimize JPEG
jpegoptim --max=85 image.jpg

# Use WebP for modern browsers
cwebp image.png -o image.webp

Lazy Loading

Use native lazy loading:

<img src="image.jpg" loading="lazy" alt="Description" />

4. Caching Strategy

Service Worker

Caching strategy (if enabled):

• Static assets: Cache indefinitely
• API responses: Network first, fallback to cache
• HTML: Network first, always

Browser Caching

Headers set by server:

Cache-Control: max-age=31536000 (1 year) for /assets/*
Cache-Control: max-age=3600 (1 hour) for /index.html

5. Rendering Performance

Virtual Scrolling

For large lists (>100 items), use virtual scrolling:

<virtual-scroller
  :items="items"
  :item-size="50"
  class="list-container"
>
  <template #default="{ item }">
    <div>{{ item.name }}</div>
  </template>
</virtual-scroller>

Lighthouse Scores Target

Current targets (Lighthouse v10):

• Performance: 90+
• Accessibility: 95+
• Best Practices: 90+
• SEO: 90+
• PWA: 90+

6. Monitoring

Core Web Vitals

Monitor these key metrics:

• LCP (Largest Contentful Paint): < 2.5s
• FID (First Input Delay): < 100ms
• CLS (Cumulative Layout Shift): < 0.1

Performance API

// Custom timing
performance.mark('operation-start')
// ... do work ...
performance.mark('operation-end')
performance.measure('operation', 'operation-start', 'operation-end')

const measure = performance.getEntriesByName('operation')[0]
console.log(`Operation took ${measure.duration}ms`)

7. Network Optimization

HTTP/2 Server Push

Critical assets are pushed by server:

• tokens.css
• main.js (critical path)

Compression

All text assets are gzip compressed (75% reduction typical).

8. Development Performance

Vite Config

Current Vite settings for optimal DX:

// vite.config.ts
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor': ['vue', 'vue-router', '@tanstack/vue-query'],
          'ui': ['@kbx/ui', 'primevue'],
        }
      }
    },
    minify: 'terser',
    target: 'esnext',
  }
}

Build Metrics

# Analyze build time
npm run build -- --debug-time

# Expected: < 30s total build time

9. Checklist

Before deployment:

• Run Lighthouse audit (all scores ≥ 90)
• Test on 3G network (DevTools throttling)
• Verify images are optimized
• Check bundle size < limits
• Run E2E tests (all passing)
• Verify accessibility (axe audit)
• Test on real mobile device
• Monitor Real User Metrics (RUM)

10. References

• Vite Performance
• Vue Performance Guide
• Web Vitals
• Lighthouse