Build Process

LamaPress uses Vite 7 for fast development and optimized production builds. This guide explains the build system, how it works, and how to use it effectively.

Table of Contents

• Overview
• Development Mode
• Production Build
• Asset Management
• Vite Configuration
• Hot Module Replacement

Overview

The build process handles:

1. JavaScript - ES6+ modules, code splitting, tree shaking
2. SCSS - Compilation, autoprefixing, minification
3. Assets - Image optimization, font loading
4. Manifest - Asset versioning and cache busting

Development Mode

Starting Development Server

npm run dev

This starts the Vite development server with:

• Hot Module Replacement (HMR)
• Fast refresh
• Source maps
• Live reload for PHP files

How It Works

1. Vite Server - Runs on http://localhost:5173
2. Hot File - Creates hot file in theme root
3. PHP Detection - functions/vite.php detects development mode
4. Asset Loading - Loads assets from Vite server

Development Workflow

# Terminal 1: Start Vite dev server
npm run dev

# Terminal 2: Access your site via Herd
# http://your-site.test

Important: Always access your site via the Herd URL, not localhost:5173. The Vite server runs in the background for asset compilation.

Production Build

Building for Production

npm run build

This creates an optimized production build:

1. Minification - JavaScript and CSS are minified
2. Tree Shaking - Unused code is removed
3. Code Splitting - Code is split into chunks
4. Asset Hashing - Files are hashed for cache busting
5. Manifest - Creates .vite/manifest.json

Build Output

Build output goes to dist/:

dist/
├── .vite/
│   └── manifest.json
├── assets/
│   ├── main-[hash].js
│   ├── main-[hash].css
│   ├── admin-[hash].js
│   └── admin-[hash].css
└── ...

Manifest File

The manifest maps entry points to hashed files:

{
  "main.js": {
    "file": "assets/main-abc123.js",
    "css": ["assets/main-abc123.css"]
  },
  "admin.js": {
    "file": "assets/admin-def456.js",
    "css": ["assets/admin-def456.css"]
  }
}

PHP uses this manifest to load the correct files.

Asset Management

Entry Points

Defined in vite.config.js:

rollupOptions: {
  input: {
    main: resolve(__dirname + '/main.js'),
    admin: resolve(__dirname + '/admin.js'),
  },
}

Public Assets

Public assets go in public/:

• public/fonts/ - Font files
• public/images/ - Static images
• public/svg/ - SVG icons

These are copied to dist/ during build.

Asset URLs

Use llPublic() helper for asset URLs:

<?php
$imageUrl = llPublic('images/logo.png');
// Development: http://localhost:5173/images/logo.png
// Production: /wp-content/themes/lamapress/dist/images/logo.png
?>

SVG Icons

Use llSvg() helper for SVG icons:

<?php
echo llSvg('arrow-right');
?>

SVGs are loaded from dist/svg/ or public/svg/.

Vite Configuration

Base Configuration

Located in vite.config.js:

export default defineConfig({
  root: '',
  base: process.env.NODE_ENV === 'development' 
    ? '/' 
    : `/wp-content/themes/${basename(__dirname)}/dist/`,
  
  build: {
    outDir: resolve(__dirname, './dist'),
    manifest: true,
    minify: true,
  },
  
  server: {
    port: 5173,
    strictPort: true,
  },
})

Plugins

Vite plugins used:

• liveReload - Reloads page on PHP file changes
• jsconfigPaths - Path alias resolution
• sassGlobImports - SCSS glob imports
• visualizer - Bundle analysis (optional)

Path Aliases

Path aliases are configured in jsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@src/*": ["src/*"],
      "@blocks/*": ["components/blocks/*"],
      "@parts/*": ["components/parts/*"]
    }
  }
}

Hot Module Replacement

How HMR Works

1. File Change - You edit a JavaScript or SCSS file
2. Vite Detects - Vite detects the change
3. HMR Update - Only the changed module is updated
4. Browser Updates - Browser updates without full page reload

PHP File Changes

PHP files trigger a full page reload (not HMR):

liveReload(__dirname + '/**/*.php')

HMR Limitations

HMR works for:

• ✅ JavaScript modules
• ✅ SCSS files
• ✅ Component files

HMR doesn't work for:

• ❌ PHP files (triggers reload)
• ❌ Config files (requires restart)
• ❌ vite.config.js (requires restart)

Bundle Analysis

Analyzing Bundle Size

npm run analyze

This generates a visual report showing:

• Bundle sizes
• Code splitting
• Dependency tree
• Optimization opportunities

The report opens automatically in your browser.

Best Practices

1. Always Build Before Deploying

npm run build

Why: Ensures optimized assets are included

2. Check Bundle Size

Regularly analyze bundle size:

npm run analyze

Why: Identifies optimization opportunities

3. Use Path Aliases

Use path aliases for cleaner imports:

// ✅ Good
import { app } from '@src/js/core/app'

// ❌ Avoid
import { app } from '../../../src/js/core/app'

4. Optimize Images

Optimize images before adding to public/images/:

• Use WebP format when possible
• Compress images
• Use appropriate sizes

5. Code Splitting

Leverage automatic code splitting:

• Components are automatically split
• Use dynamic imports for large dependencies
• Avoid importing entire libraries

Related Documentation

• Development Environment - Environment setup
• Vite Documentation - Official Vite docs
• Deployment Guide - Production deployment

---

Next Steps:

• Review Development Environment for setup
• Check Deployment Guide for production deployment
• Learn about Performance Optimization