routerino 2.5.0 → 2.5.1-rc1

package/README.md

@@ -525,18 +525,21 @@ import { Image } from "routerino/image";
 
 ### Image Props
 
-| Prop            | Type                        | Required | Description                                                |
-| --------------- | --------------------------- | -------- | ---------------------------------------------------------- |
-| `src`           | string                      | ✅       | Image source URL                                           |
-| `alt`           | string                      | ✅       | Alt text for accessibility                                 |
-| `priority`      | boolean                     | ❌       | Override lazy loading for hero/LCP images                  |
-| `widths`        | number[]                    | ❌       | Custom responsive widths (default: [480, 800, 1200, 1920]) |
-| `sizes`         | string                      | ❌       | Responsive sizes attribute (has smart default)             |
-| `className`     | string                      | ❌       | CSS classes (Tailwind/DaisyUI ready)                       |
-| `style`         | object                      | ❌       | Inline styles                                              |
-| `loading`       | "lazy" \| "eager"           | ❌       | Loading behavior (auto-set based on priority)              |
-| `decoding`      | "sync" \| "async" \| "auto" | ❌       | Decode timing (default: "async")                           |
-| `fetchpriority` | "high" \| "low" \| "auto"   | ❌       | Fetch priority (auto-set based on priority)                |
+| Prop            | Type                        | Required | Description                                                      |
+| --------------- | --------------------------- | -------- | ---------------------------------------------------------------- |
+| `src`           | string                      | ✅       | Image source URL (supports jpg, png, webp, avif, gif, bmp, tiff) |
+| `alt`           | string                      | ✅       | Alt text for accessibility                                       |
+| `priority`      | boolean                     | ❌       | Override lazy loading for hero/LCP images                        |
+| `widths`        | number[]                    | ❌       | Custom responsive widths (default: [480, 800, 1200, 1920])       |
+| `sizes`         | string                      | ❌       | Responsive sizes attribute (has smart default)                   |
+| `className`     | string                      | ❌       | CSS classes (Tailwind/DaisyUI ready)                             |
+| `style`         | object                      | ❌       | Inline styles                                                    |
+| `width`         | number                      | ❌       | Explicit width attribute (CLS prevention)                        |
+| `height`        | number                      | ❌       | Explicit height attribute (CLS prevention)                       |
+| `loading`       | "lazy" \| "eager"           | ❌       | Loading behavior (auto-set based on priority)                    |
+| `decoding`      | "sync" \| "async" \| "auto" | ❌       | Decode timing (default: "async")                                 |
+| `fetchpriority` | "high" \| "low" \| "auto"   | ❌       | Fetch priority (auto-set based on priority)                      |
+| `ref`           | React.Ref                   | ❌       | Forwarded to the underlying `<img>` element                      |
 
 ### Image Usage Examples
 
@@ -926,7 +929,7 @@ export default defineConfig({
       // useTrailingSlash: true, // Set to false for /about instead of /about/
       // verbose: false,
       // ssgCacheDir: "node_modules/.cache/routerino-forge", // SSG cache directory
-      // optimizeImages: true, // Enable image optimization (see below)
+      // imageOptions: {}, // Customize image optimization (see Image Optimization below)
     }),
   ],
 });
@@ -955,38 +958,42 @@ export default defineConfig({
 - Creates a 404.html page
 - Skips dynamic routes (with `:param` syntax)
 - SEO optimized: Complete HTML with meta tags
-- Image optimization: Automatic blur placeholders (LQIP)
+- Image optimization: Automatic responsive variants + blur placeholders (LQIP)
 - Easy configuration: Works out of the box with Vite and minimal setup
 
 #### Image Optimization
 
-Routerino Forge can automatically optimize images in your static builds for faster loading:
+Routerino Forge automatically processes `<Image>` components during the build to generate responsive image variants and LQIP (Low Quality Image Placeholder) blur-up effects. Image optimization is always enabled when ffmpeg is available — no flag needed to turn it on. Use `imageOptions` to customize:
 
 ```js
 routerinoForge({
-  optimizeImages: true, // Enable with defaults
-  // Or configure in detail:
-  optimizeImages: {
-    enabled: true,
-    placeholderSize: 20, // Size of blur placeholder (20x20 pixels)
-    blur: 4, // Blur radius for placeholder
-    maxSize: 10485760, // Maximum image size to process (10MB)
-    minSize: 1024, // Minimum image size to process (1KB)
-    cacheDir: "node_modules/.cache/routerino-forge", // Cache directory
+  baseUrl: "https://example.com",
+  imageOptions: {
+    widths: [480, 800, 1200, 1920], // Responsive widths to generate
+    formats: ["webp"], // Extra formats (webp is always generated)
+    placeholderSize: 20, // Height of LQIP placeholder in px
+    blur: 4, // Blur radius for LQIP placeholder
+    maxSize: 10485760, // Max source image size to process (10MB)
+    minSize: 1024, // Min source image size to process (1KB)
+    cacheDir: "node_modules/.cache/routerino-forge",
   },
 });
 ```
 
+All keys in `imageOptions` are optional — omit any to keep the default.
+
 **What it does:**
 
-- Generates tiny blur placeholders for images (base64 encoded)
-- Caches processed images to speed up subsequent builds
-- Preserves original images while enhancing loading performance
-- Skips external images (http/https), data URIs, and SVGs
-- Smart sizing: Uses aspect-ratio only to prevent layout shift without forcing dimensions
-- Hides images initially with `opacity: 0` to prevent broken image icons during load
+- Generates responsive image variants at each configured width (WebP + original format)
+- Generates LQIP blur placeholders (tiny base64 PNG shown while image loads)
+- Anti-upscaling: never generates variants wider than the source image
+- Caches generated variants to speed up subsequent builds
+- Skips external URLs (http/https), data URIs, and SVGs
+- Skips images below `minSize` or above `maxSize`
+- Adds `width`/`height` attributes to `<img>` tags for CLS prevention
+- Stale cache entries are automatically cleaned up (50 most recent kept)
 
-**Note:** Image optimization requires `ffmpeg` to be installed on your system. Install with `brew install ffmpeg` (Mac), `apt install ffmpeg` (Debian/Ubuntu), or `choco install ffmpeg` (Windows). Without ffmpeg, the Image component still works but falls back to the original image without optimization. A warning is shown during build if ffmpeg is not found but Image components are used.
+**Note:** Image optimization requires `ffmpeg` to be installed on your system. Install with `brew install ffmpeg` (Mac), `apt install ffmpeg` (Debian/Ubuntu), or `choco install ffmpeg` (Windows). Without ffmpeg, the Image component still works but falls back to the original image without responsive variants or LQIP. A warning is shown during build if ffmpeg is not found but Image components are used.
 
 ##### CI/CD Setup for Image Optimization