Frontend Asset Management

Derafu Foundation includes a pre-configured asset build system using Vite. This document explains how to work with frontend assets in your project.

• Overview
• Directory Structure
• Configuration
  • Entry Points
  • Image Optimization
• Usage
  • Adding Assets
  • Importing Assets
  • Building Assets
  • Using Built Assets
• Best Practices
• Advanced Configuration

Overview

The asset management system handles:

• CSS compilation.
• JavaScript bundling.
• Image optimization.
• Source maps generation.
• Asset versioning.

Directory Structure

project_dir/
├── assets/
│   ├── css/
│   │   └── app.css           # Main CSS file.
│   ├── img/                  # Image files.
│   └── js/
│       ├── app.js            # Main JavaScript entry point.
│       └── images.js         # Image import handling.
├── public/
│   └── static/               # Output directory (generated).
│       ├── css/
│       ├── img/
│       └── js/
└── vite.config.js            # Vite configuration.

Configuration

The Vite configuration is defined in vite.config.js. Key features include:

• Multiple entry points: app.js, app.css, and images.js.
• Output directory: public/static/.
• Custom file naming with .min suffix.
• Image optimization using vite-plugin-sharp.

Entry Points

• app.js: Main JavaScript code.
• app.css: Main CSS styles.
• images.js: Used for processing and importing images.

Image Optimization

Images are automatically optimized during the build process using the Sharp image processing library. The configuration includes:

• PNG compression: Quality 85%, maximum compression level.
• JPEG compression: Quality 85%, progressive encoding.
• Automatic resizing of large images to a maximum of 2000×2000 pixels.

Usage

Adding Assets

1. CSS: Add your CSS files to the assets/css/ directory.
2. JavaScript: Add your JavaScript files to the assets/js/ directory.
3. Images: Add your images to the assets/img/ directory.

Importing Assets

CSS

In your main app.css file:

/* Import other CSS files */
@import './components/buttons.css';

JavaScript

In your JavaScript files:

// Import other JavaScript files.
import './components/slider.js';

// Import CSS from JavaScript.
import '../css/components/modal.css';

// Import images.
import logo from '../img/logo.png';

Images

For processing multiple images at once, use the images.js file:

// Import all images in a directory.
import.meta.glob('../img/**/*');

Building Assets

To build assets for production:

npm run build

This will:

1. Compile and bundle all assets.
2. Optimize images.
3. Generate minified files with source maps.
4. Output everything to the public/static/ directory.

Using Built Assets

In your HTML/Twig templates, reference the built assets:

<link rel="stylesheet" href="/static/css/app.min.css">
<script src="/static/js/app.min.js"></script>
<img src="/static/img/logo.png">

Best Practices

1. Organize by component: Group related CSS, JS, and images by feature or component.
2. Optimize images before adding: While the build process optimizes images, starting with optimized images is better.
3. Use CSS imports: Keep CSS modular by using imports.
4. Lazy load images: For image-heavy pages, consider implementing lazy loading.
5. Watch file size: Monitor the size of your built assets to ensure optimal loading times.

Advanced Configuration

The Vite configuration can be extended to support:

• CSS preprocessors (Sass, Less, etc.).
• TypeScript.
• Additional plugins for specific needs.
• Custom output paths and formats.

To modify the configuration, edit the vite.config.js file as needed (remember to deactivate the Derafu\\Foundation\\Installer::copyFiles from the post-install-cmd and post-update-cmd scripts in your composer.json file).