Build & Optimization Guide

Build & Optimization Guide

This guide covers the build process, performance optimization strategies, and deployment best practices.

Build Process

Development Build

# Start development server
bun run dev

# Development features:
# - Hot Module Replacement (HMR)
# - No minification
# - Source maps
# - Development-only features enabled

Production Build

# Create production build
bun run build

# Production features:
# - Code minification
# - Tree shaking
# - Image optimization
# - CSS optimization
# - No source maps

Performance Optimization

1. Image Optimization

We use Astro’s built-in image optimization:

---
import { OptimizedImage } from '@/components/media/OptimizedImage.astro';
---

<OptimizedImage
  src={import('@/assets/image.png')}
  alt="Description"
  width={800}
  height={600}
/>

<!-- Features:
- WebP conversion
- Responsive sizes
- Lazy loading
- Aspect ratio preservation
- Zero layout shift
-->

2. CSS Optimization

Tailwind’s built-in optimizations:

// tailwind.config.mjs
export default {
  // Remove unused styles in production
  content: ["./src/**/*.{astro,html,js,jsx,md,mdx,ts,tsx}"],
  
  // Minify class names
  future: {
    hoverOnlyWhenSupported: true,
  },
}

3. JavaScript Optimization

// Dynamic imports for code splitting
const DynamicComponent = lazy(() => import('./DynamicComponent'));

// Preload critical components
<link rel="modulepreload" href="/components/critical.js" />;

// Defer non-critical JavaScript
<script type="module" defer src="/components/non-critical.js" />;

4. Font Optimization

---
// src/components/layout/BaseHead.astro
---

<!-- Preload critical fonts -->
<link
  rel="preload"
  href="/fonts/inter-var.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>

<!-- Use font-display: swap -->
<style>
  @font-face {
    font-family: 'Inter Variable';
    font-display: swap;
    src: url('/fonts/inter-var.woff2') format('woff2');
  }
</style>

Build Configuration

1. Astro Config

// astro.config.mjs
export default defineConfig({
  output: 'static',
  build: {
    // Optimize build
    inlineStylesheets: 'auto',
    split: true,
    
    // Assets
    assets: 'assets',
    assetsPrefix: 'https://cdn.example.com',
  },
  
  // Image optimization
  image: {
    service: { entrypoint: 'astro/assets/services/sharp' },
    remotePatterns: [{ protocol: 'https' }],
  },
});

2. TypeScript Config

// tsconfig.json
{
  "compilerOptions": {
    // Build optimization
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    
    // Type checking
    "strict": true,
    "skipLibCheck": true,
  }
}

3. PostCSS Config

// postcss.config.js
export default {
  plugins: {
    'tailwindcss/nesting': {},
    tailwindcss: {},
    autoprefixer: {},
    ...(process.env.NODE_ENV === 'production'
      ? { cssnano: { preset: 'default' } }
      : {})
  }
}

Performance Monitoring

1. Core Web Vitals

Monitor key metrics:

  • Largest Contentful Paint (LCP)
  • First Input Delay (FID)
  • Cumulative Layout Shift (CLS)
// Measure LCP
new PerformanceObserver((list) => {
  const entries = list.getEntries();
  const lcpEntry = entries[entries.length - 1];
  console.log('LCP:', lcpEntry.startTime);
}).observe({ entryTypes: ['largest-contentful-paint'] });

2. Bundle Analysis

# Analyze bundle size
npm run build -- --analyze

# Key metrics to monitor:
# - Total bundle size
# - Individual chunk sizes
# - Duplicate modules
# - Tree-shaking effectiveness

Deployment Optimization

1. Static Asset Handling

# nginx.conf
http {
  # Cache static assets
  location /assets/ {
    expires 1y;
    add_header Cache-Control "public, no-transform";
  }
  
  # Cache fonts
  location /fonts/ {
    expires 1y;
    add_header Cache-Control "public, no-transform";
  }
}

2. Environment Configuration

# .env.production
PUBLIC_SITE_URL=https://example.com
PUBLIC_ASSETS_URL=https://cdn.example.com
PUBLIC_API_URL=https://api.example.com

# Features:
# - CDN integration
# - API endpoint configuration
# - Analytics setup

3. Docker Production Build

# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY . .
RUN npm ci
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

Optimization Checklist

Build Process

  • Enable production mode
  • Verify tree shaking
  • Check bundle sizes
  • Optimize dependencies

Assets

  • Compress images
  • Optimize fonts
  • Minify CSS/JS
  • Configure caching

Performance

  • Measure Core Web Vitals
  • Check Lighthouse score
  • Monitor bundle size
  • Test load times

Deployment

  • Set up CDN
  • Configure caching
  • Enable compression
  • Monitor errors

Troubleshooting

Common Build Issues

  1. Large Bundle Sizes

    • Use dynamic imports
    • Enable tree shaking
    • Remove unused dependencies

  2. Slow Build Times

    • Use build caching
    • Optimize asset processing
    • Parallel builds

  3. Memory Issues

    • Increase Node.js memory limit
    • Optimize image processing
    • Use incremental builds

Best Practices

  1. Regular Monitoring

    • Track performance metrics
    • Monitor error rates
    • Check bundle sizes

  2. Continuous Optimization

    • Regular dependency updates
    • Performance audits
    • User experience testing

  3. Documentation

    • Document build process
    • Maintain deployment guides
    • Track optimization decisions
development
documentation
performance