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
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
, andimages.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
- CSS: Add your CSS files to the
assets/css/
directory. - JavaScript: Add your JavaScript files to the
assets/js/
directory. - 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:
- Compile and bundle all assets.
- Optimize images.
- Generate minified files with source maps.
- 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
- Organize by component: Group related CSS, JS, and images by feature or component.
- Optimize images before adding: While the build process optimizes images, starting with optimized images is better.
- Use CSS imports: Keep CSS modular by using imports.
- Lazy load images: For image-heavy pages, consider implementing lazy loading.
- 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).