routerino 2.5.0 → 2.5.1-rc10

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
 
@@ -1069,6 +1076,35 @@ In your netlify.toml:
   publish = "dist"
 ```
 
+###### Cloudflare Pages
+
+Cloudflare Pages doesn't allow `apt-get`. Use the `ffmpeg-static` / `ffprobe-static` npm packages instead.
+
+In the **Cloudflare Pages dashboard** under **Settings > Build & Deployments > Build command**:
+
+```
+npm ci && npm install --no-save ffmpeg-static ffprobe-static && ln -sf "$(node -e "console.log(require('ffmpeg-static'))")" /tmp/ffmpeg && ln -sf "$(node -e "console.log(require('ffprobe-static').path)")" /tmp/ffprobe && export PATH="/tmp:$PATH" && npm run build
+```
+
+Or in your `wrangler.toml`:
+
+```toml
+[build]
+command = """
+  npm ci && \
+  npm install --no-save ffmpeg-static ffprobe-static && \
+  ln -sf "$(node -e "console.log(require('ffmpeg-static'))")" /tmp/ffmpeg && \
+  ln -sf "$(node -e "console.log(require('ffprobe-static').path)")" /tmp/ffprobe && \
+  export PATH="/tmp:$PATH" && \
+  npm run build
+"""
+
+[build.environment]
+NODE_VERSION = "20"
+```
+
+> **Note:** Without ffmpeg, the SSG still builds successfully — the forge plugin automatically strips responsive image references so browsers load the original images without 404s. Install ffmpeg to enable WebP variants, LQIP blur placeholders, and responsive image sets for better Lighthouse scores.
+
 #### Routes Configuration
 
 **Critical for SSG**: Routes MUST be exported for the build plugin to discover them. The plugin needs to import your routes at build time, so inline route definitions won't work.