routerino 2.4.0 → 2.5.1-rc1

package/README.md

@@ -1,6 +1,6 @@
 # Routerino
 
-> A lightweight, SEO-optimized React router for modern websites and applications
+> A lightweight, SEO-optimized React router & SSG for modern websites and applications
 
 For teams who want SPA simplicity with search-friendly static HTML, Open Graph previews, and **no framework lock-in.**
 
@@ -129,7 +129,18 @@ export const routes = [
 />;
 ```
 
-Links are just standard HTML anchor tags. No need to use special `<Link>` components—you can use whatever components or design system you like. For example: <a href="/some-page/">a link</a> is perfectly valid. This is very handy for markdown-based content. With standard link support in Routerino, you won't need to [transform your markdown content with custom React components](https://github.com/remarkjs/react-markdown?tab=readme-ov-file#appendix-b-components). Routerino handles same-origin anchor clicks. Cross-origin links and non-HTTP schemes (e.g., mailto:, tel:) are handled by the browser as usual.
+Links are just standard HTML anchor tags. No need to use special `<Link>` components—you can use whatever components or design system you like. For example: <a href="/some-page/">a link</a> is perfectly valid. This is very handy for markdown-based content. With standard link support in Routerino, you won't need to [transform your markdown content with custom React components](https://github.com/remarkjs/react-markdown?tab=readme-ov-file#appendix-b-components).
+
+Routerino handles same-origin anchor clicks via SPA navigation. The browser handles the rest natively, including:
+
+- **Cross-origin links** (different domain)
+- **Non-HTTP schemes** (mailto:, tel:, javascript:, etc.)
+- **Modified clicks** (Ctrl/Cmd+click, Shift+click, Alt+click, right-click)
+- **`target="_blank"`** links
+- **`download`** attribute links
+- **`rel="external"`** links
+- **File extension links** — PDFs, ZIPs, images, fonts, videos, JSON, XML, and 50+ other file types are recognized automatically
+- **Custom patterns** — use the [`ignorePatterns`](#ignorepatterns-string) prop for additional exclusions (e.g., `/api/`, `/legacy/`)
 
 ### Programmatic Navigation
 
@@ -224,6 +235,7 @@ All of these are optional, so it's easy to get started with nothing but a bare-b
 | [imageUrl](#imageurl-string)                   | string          | Default image URL for sharing     | `null`                        |
 | [touchIconUrl](#touchiconurl-string)           | string          | Image URL for PWA homescreen icon | `null`                        |
 | [debug](#debug-boolean)                        | boolean         | Enable debug mode                 | `false`                       |
+| [ignorePatterns](#ignorepatterns-string)       | string[]        | URL patterns to skip SPA routing  | `[]`                          |
 
 ##### `title`: string;
 
@@ -300,7 +312,9 @@ Default: `false`
 
 ##### `baseUrl`: string;
 
-The base URL to use for canonical tags and og:url meta tags. If not provided, uses `window.location.origin`. This is useful when you want to specify the production URL regardless of the current environment.
+The base URL to use for canonical tags and og:url meta tags. If not provided, uses `window.location.origin`.
+
+This is useful when your site is accessible from multiple domains (for example, both example.com and example.net point to the same app). Set it to the preferred domain and all canonical and og:url tags will consistently point there. Also helpful for pinning to the production URL in development or staging environments.
 
 **Important:** The baseUrl must NOT end with a trailing slash (`/`). Correct example: `"https://example.com"`
 
@@ -338,6 +352,21 @@ Example debug output:
 
 Default: `false`
 
+##### `ignorePatterns`: string[];
+
+An array of regex pattern strings to match against link hrefs. Any same-origin link matching one of these patterns will **not** be intercepted by the SPA router — the browser will handle the navigation natively instead.
+
+Patterns are tested case-insensitively against the full resolved href (including origin).
+
+```jsx
+// Skip API endpoints and a legacy section
+<Routerino routes={routes} ignorePatterns={["/api/", "/admin/legacy/"]} />
+```
+
+Routerino also has a built-in list of file extensions that are automatically skipped: `.pdf`, `.zip`, `.docx`, `.png`, `.jpg`, `.svg`, `.mp4`, `.json`, `.xml`, `.csv`, `.txt`, `.ico`, `.woff2`, `.woff`, `.ttf`, `.mp3`, `.wav`, `.epub`, `.map`, `.css`, `.js`, `.wasm`, and many more. The `ignorePatterns` prop is for additional custom patterns beyond these defaults.
+
+Default: `[]`
+
 #### RouteConfig props
 
 There is a default RouteConfig that will be loaded if you don't specify any routes. The default route is a basic template that can confirm your app is working and routing is good to go.
@@ -402,6 +431,31 @@ An array of HeadTag objects that can be added to the route to manage meta tags,
 
 - `target` (string): The "target" attribute of the tag. Defines where to open the linked resource.
 
+- `innerHTML` (string): Inner HTML content for tags that require a closing tag, such as `<script>` and `<style>`. When provided, the tag is rendered as `<tag attrs>innerHTML</tag>` instead of a self-closing element. This enables structured data (JSON-LD), inline CSS, and other tag-body content.
+
+##### Structured Data Example
+
+```jsx
+{
+  path: "/about/",
+  element: <AboutPage />,
+  tags: [{
+    tag: "script",
+    type: "application/ld+json",
+    innerHTML: JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "BreadcrumbList",
+      itemListElement: [
+        { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
+        { "@type": "ListItem", "position": 2, "name": "About", "item": "https://example.com/about/" },
+      ],
+    }),
+  }],
+}
+```
+
+This works both at runtime (via `updateHeadTag`) and during static site generation (via the forge plugin).
+
 ### Using the `useRouterino` Hook
 
 The `useRouterino` hook provides access to router state from any child component. This is the primary way to access route information and update head tags dynamically.
@@ -471,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
 
@@ -717,6 +774,8 @@ With Prerender (SPA):
 
 You can override the default with `useTrailingSlash={false}` if you prefer URLs without trailing slashes. Either way, Routerino ensures search engines see consistent, canonical URLs.
 
+**Multi-domain deployments**: If your site is served from multiple domains, set `baseUrl` to the preferred domain to keep all canonical and og:url tags pointing to one place. For example, `<Routerino baseUrl="https://example.com" routes={routes} />` ensures search engines see one canonical domain even when the same page is reachable at example.net.
+
 ### Sitemap Generation
 
 - Automate the creation of `sitemap.xml` and `robots.txt` during your build process with Routerino Forge.
@@ -808,14 +867,14 @@ This creates an engaging Twitter preview with a large image, title, and descript
 ### Additional SEO Considerations
 
 - Use semantic HTML elements in your components for better content structure.
-- Implement structured data (JSON-LD) where applicable to enhance rich snippets in search results.
+- Implement structured data (JSON-LD) where applicable to enhance rich snippets in search results. Use the `innerHTML` property on a `<script type="application/ld+json">` head tag (see the [Structured Data Example](#structured-data-example) above).
 - Ensure your site is mobile-friendly and loads quickly for better search engine rankings.
 
 By following these practices, you'll improve your site's SEO performance and social media presence when using Routerino.
 
 ### Hash Links
 
-Routerino supports standard `<a href="/page#section">` links for SPA navigation — after React renders the new page, it finds the element with the matching `id` and scrolls it into view.
+Routerino supports standard `<a href="/page#section">` links for SPA navigation. After React renders the new page, it finds the element with the matching `id` and scrolls it into view.
 
 **Sticky headers**: If your site has a fixed header, use the CSS [`scroll-margin-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) property to offset the scroll target so content isn't hidden behind the header:
 
@@ -870,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)
     }),
   ],
 });
@@ -899,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