routerino 2.2.0 → 2.2.2-rc1

package/README.md

@@ -4,8 +4,6 @@
 
 For teams who want SPA simplicity with search-friendly static HTML, Open Graph previews, and **no framework lock-in.**
 
-<!-- [**Live Example**](https://www.papoir.com) | [**Starter Template**](https://github.com/nerds-with-keyboards/routerino-starter) -->
-
 Routerino is a zero-dependency router for React designed for optimal SEO performance in client-side rendered applications. Built for modern web architectures like JAMStack applications and Vite-powered React sites, it provides route & meta tag management, sitemap generation, and static site generation or [prerender](https://github.com/prerender/prerender) support to ensure your React applications are fully discoverable by search engines.
 
 ## Why Routerino?
@@ -204,7 +202,7 @@ The table below shows all available props with their default values. See the [us
 
 #### Routerino props
 
-All of these are optional, so it's easy to get started with nothing but a bare-bones `<Routerino />` element, to get started with a working sample page. The main props you'll need are `routes` and `title`. See [Route props](#routes-prop) for the route format.
+All of these are optional, so it's easy to get started with nothing but a bare-bones `<Routerino />` element, to get started with a working sample page. The main props you'll need are `routes` and `title`. See [RouteConfig props](#routeconfig-props) for the route format.
 
 | Prop                                           | Type            | Description                       | Default                       |
 | ---------------------------------------------- | --------------- | --------------------------------- | ----------------------------- |
@@ -685,10 +683,9 @@ export default defineConfig({
     routerinoForge({
       baseUrl: "https://example.com", // Your production URL (no trailing slash)
       // Optional settings (these are the defaults):
-      // routes: "./src/routes.jsx", // Your routes file
+      // routes: "./src/routes.jsx", // Your routes file (and App.jsx for full layout)
       // outputDir: "dist",
       // generateSitemap: true,
-      // prerenderStatusCode: true,
       // useTrailingSlash: true, // Set to false for /about instead of /about/
       // verbose: false,
       // ssgCacheDir: "node_modules/.cache/routerino-forge", // SSG cache directory
@@ -749,6 +746,8 @@ routerinoForge({
 - 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
 
 **Note:** Image optimization requires `ffmpeg` to be installed. Without it, images work normally but without blur placeholders. Install with `brew install ffmpeg` (Mac), `apt install ffmpeg` (Ubuntu), or `choco install ffmpeg` (Windows).
 
@@ -837,6 +836,28 @@ In your netlify.toml:
 
 **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.
 
+To include your full layout (headers, footers, etc.) in static generated HTML, export routes from the same file as your App component:
+
+```jsx
+// App.jsx - export routes from here for full layout SSG
+export const routes = [
+  { path: "/", element: <HomePage />, title: "Home" },
+  { path: "/about/", element: <AboutPage />, title: "About" },
+];
+
+export default function App() {
+  return (
+    <main>
+      <Header />
+      <Routerino routes={routes} />
+      <Footer />
+    </main>
+  );
+}
+```
+
+This ensures your entire App layout is rendered during static site generation. Without this, SSG renders only the individual route elements.
+
 Define routes with an `element` property containing JSX elements:
 
 ```jsx
@@ -1005,9 +1026,7 @@ If you're starting from scratch and wondering "How do I create a React project w
 2. We recommend using [Vite](https://vitejs.dev/) for a fast and lean development experience. Vite is a modern build tool that focuses on speed and simplicity. To create a new React project with Vite, run the following command in your terminal:
 
 ```
-
 npm create vite@latest my-react-app -- --template react
-
 ```
 
 This command will create a new directory called `my-react-app` with a basic React project structure.
@@ -1015,17 +1034,13 @@ This command will create a new directory called `my-react-app` with a basic Reac
 3. Navigate to your new project directory:
 
 ```
-
 cd my-react-app
-
 ```
 
 4. Install the project dependencies using npm:
 
 ```
-
 npm install
-
 ```
 
 This command will read the `package.json` file in your project and install all the necessary dependencies.
@@ -1033,14 +1048,12 @@ This command will read the `package.json` file in your project and install all t
 5. Now, add Routerino to your project as a dependency:
 
 ```
-
 npm install routerino
-
 ```
 
 This command will install the latest version of Routerino and save it to your `package.json` file under the `dependencies` section.
 
-With these steps, you'll have a new React project set up with Vite as the build tool and Routerino installed as a development dependency. You can now start building your application with React & Routerino.
+With these steps, you'll have a new React project set up with Vite as the build tool and Routerino installed as a dependency. You can now start building your application with React & Routerino.
 
 ### Full React Example
 
@@ -1207,6 +1220,7 @@ By vendoring Routerino, you have full control over the code and can make any nec
 
 Here are some sources for further reading on SEO best-practices.
 
+- [Optimize Largest Contentful Paint (LCP)](https://web.dev/articles/optimize-lcp) - Improve loading performance
 - [Apple's best practices for link previews](https://developer.apple.com/library/archive/technotes/tn2444/_index.html)
 - [Use Open Graph tags](https://ahrefs.com/blog/open-graph-meta-tags/)
 - [Use descriptive link text](https://developers.google.com/search/docs/fundamentals/seo-starter-guide?hl=en&ref_topic=9460495)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "routerino",
-  "version": "2.2.0",
+  "version": "2.2.2-rc1",
   "description": "A lightweight, SEO-optimized React router for modern web applications",
   "repository": {
     "type": "git",

package/routerino-forge.js

@@ -217,84 +217,118 @@ async function processImagesInHTML(html, outputDir, config) {
   const cacheDir = path.resolve(imageConfig.cacheDir);
   await fs.mkdir(cacheDir, { recursive: true }).catch(() => {});
 
-  // Find all img tags
+  // Find all img tags - process in chunks to optimize memory
   const imgRegex = /<img\s+([^>]*?)src=["']([^"']+)["']([^>]*?)>/gi;
-  const matches = [...html.matchAll(imgRegex)];
-
   let processedHTML = html;
 
-  for (const match of matches) {
-    // eslint-disable-next-line no-unused-vars
-    const [fullMatch, beforeSrc, src, afterSrc] = match;
-
-    // Skip external URLs, data URLs, and SVGs
-    if (shouldSkipImage(src)) {
-      stats.skipped++;
-      continue;
+  // Process images in batches to avoid loading all matches at once
+  const BATCH_SIZE = 10; // Process 10 images at a time
+  let match;
+  let batchCount = 0;
+  let currentBatch = [];
+
+  while ((match = imgRegex.exec(html)) !== null) {
+    currentBatch.push(match);
+    batchCount++;
+
+    // Process batch when it reaches the size limit
+    if (batchCount >= BATCH_SIZE) {
+      processedHTML = await processBatch(currentBatch, processedHTML);
+      currentBatch = [];
+      batchCount = 0;
     }
+  }
 
-    // Resolve image path
-    const imagePath = path.join(outputDir, src);
+  // Process remaining images in the last batch
+  if (currentBatch.length > 0) {
+    processedHTML = await processBatch(currentBatch, processedHTML);
+  }
 
-    // Check if file exists and size
-    try {
-      const fileStats = await fs.stat(imagePath);
+  // Helper function to process a batch of images
+  async function processBatch(batch, html) {
+    let result = html;
 
-      if (
-        fileStats.size < imageConfig.minSize ||
-        fileStats.size > imageConfig.maxSize
-      ) {
+    for (const match of batch) {
+      // eslint-disable-next-line no-unused-vars
+      const [fullMatch, beforeSrc, src, afterSrc] = match;
+
+      // Skip external URLs, data URLs, and SVGs
+      if (shouldSkipImage(src)) {
         stats.skipped++;
         continue;
       }
 
-      stats.totalSize += fileStats.size;
+      // Resolve image path with safety check
+      const imagePath = path.join(outputDir, src);
 
-      // Check cache
-      const cacheKey = await getImageCacheKey(imagePath, imageConfig);
-      if (!cacheKey) {
+      // Path traversal protection: ensure resolved path is within outputDir
+      const resolvedPath = path.resolve(imagePath);
+      const resolvedOutputDir = path.resolve(outputDir);
+      if (!resolvedPath.startsWith(resolvedOutputDir)) {
+        // Skip potentially malicious paths
         stats.skipped++;
         continue;
       }
 
-      const cacheFile = path.join(cacheDir, `${cacheKey}.json`);
-      let imageData;
-
+      // Check if file exists and size
       try {
-        // Try to read from cache
-        const cached = JSON.parse(await fs.readFile(cacheFile, "utf-8"));
-        imageData = cached;
-      } catch {
-        // Generate placeholder
-        imageData = await generatePlaceholder(imagePath, imageConfig);
-
-        if (!imageData) {
+        const fileStats = await fs.stat(resolvedPath);
+
+        if (
+          fileStats.size < imageConfig.minSize ||
+          fileStats.size > imageConfig.maxSize
+        ) {
           stats.skipped++;
           continue;
         }
 
-        // Save to cache
-        await fs
-          .writeFile(cacheFile, JSON.stringify(imageData))
-          .catch(() => {});
-      }
+        stats.totalSize += fileStats.size;
 
-      const dataUri = imageData.placeholder;
+        // Check cache
+        const cacheKey = await getImageCacheKey(resolvedPath, imageConfig);
+        if (!cacheKey) {
+          stats.skipped++;
+          continue;
+        }
 
-      // Create a wrapper span with the blurred background positioned behind
-      // Set explicit dimensions if we have them to show placeholder before image loads
-      let spanStyle = `position: relative; display: inline-block;`;
+        const cacheFile = path.join(cacheDir, `${cacheKey}.json`);
+        let imageData;
 
-      if (imageData.width && imageData.height) {
-        spanStyle += ` width: ${imageData.width}px; height: ${imageData.height}px;`;
-      }
+        try {
+          // Try to read from cache
+          const cached = JSON.parse(await fs.readFile(cacheFile, "utf-8"));
+          imageData = cached;
+        } catch {
+          // Generate placeholder
+          imageData = await generatePlaceholder(resolvedPath, imageConfig);
 
-      // Create the blur background as a pseudo-element that sits behind (z-index: -1)
-      // Using a unique class to avoid conflicts
-      const uniqueClass = `lqip-${Math.random().toString(36).substr(2, 9)}`;
+          if (!imageData) {
+            stats.skipped++;
+            continue;
+          }
+
+          // Save to cache
+          await fs
+            .writeFile(cacheFile, JSON.stringify(imageData))
+            .catch(() => {});
+        }
+
+        const dataUri = imageData.placeholder;
 
-      // Style for the ::before pseudo-element that creates the blur background
-      const beforeStyle = `
+        // Create a wrapper span with the blurred background positioned behind
+        let spanStyle = `position: relative; display: inline-block;`;
+
+        if (imageData.width && imageData.height) {
+          // Set aspect-ratio for proper proportions
+          const aspectRatio = imageData.width / imageData.height;
+          spanStyle += ` aspect-ratio: ${aspectRatio};`;
+        }
+
+        // Create the blur background as a pseudo-element that sits behind (z-index: -1)
+        // Using a unique class to avoid conflicts
+        const uniqueClass = `lqip-${Math.random().toString(36).substring(2, 11)}`;
+        // Style for the ::before pseudo-element that creates the blur background
+        const beforeStyle = `
         .${uniqueClass}::before {
           content: '';
           position: absolute;
@@ -310,20 +344,44 @@ async function processImagesInHTML(html, outputDir, config) {
         }
       `;
 
-      const styleTag = `<style>${beforeStyle}</style>`;
+        const styleTag = `<style>${beforeStyle}</style>`;
+
+        // Add opacity: 0 inline style to hide image initially
+        const imgWithOpacity = fullMatch.replace(
+          /(<img\s+[^>]*?)(\s*\/?>)/i,
+          (_, p1, p2) => {
+            let result = p1;
+
+            // Add opacity to style
+            if (/style\s*=/i.test(result)) {
+              // Add to existing style
+              result = result.replace(
+                /style\s*=\s*["']([^"']*)/i,
+                'style="opacity: 0; $1'
+              );
+            } else {
+              // Add new style attribute
+              result += ' style="opacity: 0"';
+            }
 
-      // Wrap img in span with blur background, leaving img completely untouched
-      const wrappedImg = `${styleTag}<span class="forge-lqip ${uniqueClass}" style="${spanStyle}">${fullMatch}</span>`;
+            return result + p2;
+          }
+        );
 
-      processedHTML = processedHTML.replace(fullMatch, wrappedImg);
+        // Wrap img in span with blur background
+        const wrappedImg = `${styleTag}<span class="forge-lqip ${uniqueClass}" style="${spanStyle}">${imgWithOpacity}</span>`;
 
-      stats.processed++;
-      stats.placeholderSize += imageData.placeholder.length;
-    } catch (error) {
-      stats.errors.push({ src, error: error.message });
-      stats.skipped++;
-    }
-  }
+        result = result.replace(fullMatch, wrappedImg);
+
+        stats.processed++;
+        stats.placeholderSize += imageData.placeholder.length;
+      } catch (error) {
+        stats.errors.push({ src, error: error.message });
+        stats.skipped++;
+      }
+    } // End of for loop in processBatch
+    return result;
+  } // End of processBatch function
 
   return { html: processedHTML, stats };
 }
@@ -368,6 +426,9 @@ export function routerinoForge(options = {}) {
     },
 
     async closeBundle() {
+      // Only run during build, not during dev server
+      if (viteConfig.command !== "build") return;
+
       if (hasRun || viteConfig.build.ssr) return; // Skip if already run or if this IS the SSG build
       hasRun = true;
 
@@ -407,22 +468,103 @@ export function routerinoForge(options = {}) {
 import React from 'react';
 import ReactDOMServer from 'react-dom/server';
 import * as routesModule from '${relativePath.startsWith(".") ? relativePath : "./" + relativePath}';
+
 // Support different export patterns  
 const routes = routesModule.routes || routesModule.default;
 const notFoundTemplate = routesModule.notFoundTemplate;
+
+// Check if App component is exported from routes file
+const App = routesModule.App || routesModule.default?.App;
+
 if (!routes) {
   throw new Error('Could not find routes export. Expected "export const routes" or "export default" from ${relativePath}');
 }
+
 // Helper to check if a route is dynamic (contains :param)
 const isDynamicRoute = (path) => path.split("/").some(segment => segment.startsWith(":"));
 export { routes };
-export function render(url) {
+
+// Mock minimal window object for SSG
+function mockWindow(url, baseUrl) {
+  const urlObj = new URL(url, baseUrl || 'http://localhost');
+  global.window = {
+    location: {
+      href: urlObj.href,
+      pathname: urlObj.pathname,
+      search: urlObj.search,
+      hash: urlObj.hash,
+      origin: urlObj.origin,
+      protocol: urlObj.protocol,
+      host: urlObj.host,
+      hostname: urlObj.hostname,
+      port: urlObj.port
+    },
+    history: {
+      pushState: () => {},
+      replaceState: () => {}
+    },
+    scrollTo: () => {},
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    dispatchEvent: () => {}
+  };
+  global.document = {
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    querySelector: () => null,
+    createElement: () => ({ 
+      setAttribute: () => {},
+      appendChild: () => {}
+    }),
+    head: {
+      appendChild: () => {}
+    }
+  };
+}
+
+export function render(url, baseUrl) {
+  // Check if we should render the full App or just the route element
+  if (App) {
+    // Mock window for the current route
+    mockWindow(url, baseUrl);
+    
+    try {
+      // Render the full App component (which includes Routerino)
+      const html = ReactDOMServer.renderToString(React.createElement(App));
+      
+      // Find the rendered route to get its metadata
+      const route = routes.find(r => {
+        if (r.path === url) return true;
+        if (r.path === '/' && url === '/') return true;
+        if (isDynamicRoute(r.path)) return false;
+        return r.path === url;
+      });
+      
+      return {
+        html,
+        title: route?.title,
+        description: route?.description,
+        imageUrl: route?.imageUrl,
+        notFound: !route
+      };
+    } catch (error) {
+      console.error(\`[Routerino Forge] Failed to render App for route \${url}:\`, error.message);
+      // Fall back to route-only rendering
+    } finally {
+      // Clean up global mocks
+      delete global.window;
+      delete global.document;
+    }
+  }
+  
+  // Original behavior: render just the route element
   const route = routes.find(r => {
     if (r.path === url) return true;
     if (r.path === '/' && url === '/') return true;
     if (isDynamicRoute(r.path)) return false;
     return r.path === url;
   }); 
+  
   if (!route) {
     if (notFoundTemplate) {
       const notFoundHTML = ReactDOMServer.renderToString(notFoundTemplate);
@@ -430,6 +572,7 @@ export function render(url) {
     }
     return { html: '<div><h1>404 - Page Not Found</h1><p>The page you are looking for does not exist.</p></div>', notFound: true };
   }
+  
   try {
     const html = ReactDOMServer.renderToString(route.element);
     return {
@@ -549,7 +692,7 @@ export function render(url) {
         }
 
         // Check if template has the root div
-        if (!template.includes('<div id="root">')) {
+        if (!/<div[^>]*\sid=["']root["'][^>]*>/i.test(template)) {
           console.warn(
             '[Routerino Forge] Template missing <div id="root">. The plugin needs this to inject rendered HTML.'
           );
@@ -683,8 +826,8 @@ async function generateStaticPages({
     }
 
     try {
-      // Use the render function to generate HTML
-      const renderResult = render(route.path);
+      // Use the render function to generate HTML (pass baseUrl for window mocking)
+      const renderResult = render(route.path, config.baseUrl);
 
       let renderedHTML = "";
       if (renderResult.notFound) {
@@ -774,11 +917,10 @@ async function generateStaticPages({
         html = html.replace("</head>", `  ${metaTags}\n  </head>`);
 
         // Replace root div content with rendered HTML
-        if (html.includes('<div id="root">')) {
-          html = html.replace(
-            /<div id="root">.*?<\/div>/s,
-            `<div id="root">${renderedHTML}</div>`
-          );
+        const rootDivRegex =
+          /(<div[^>]*\sid=["']root["'][^>]*>)(.*?)(<\/div>)/is;
+        if (rootDivRegex.test(html)) {
+          html = html.replace(rootDivRegex, `$1${renderedHTML}$3`);
         } else {
           console.warn(
             `[Routerino Forge] Could not find <div id="root"> for ${route.path}`
@@ -823,6 +965,29 @@ async function generateStaticPages({
   return allImageStats;
 }
 
+// Helper to safely handle meta tag content
+// If content has double quotes, use single quotes for the attribute
+// If content has single quotes, use double quotes for the attribute
+// If it has both, replace double quotes with smart quotes
+function formatMetaAttribute(attrName, content) {
+  if (!content) return "";
+
+  const hasDoubleQuotes = content.includes('"');
+  const hasSingleQuotes = content.includes("'");
+
+  if (hasDoubleQuotes && hasSingleQuotes) {
+    // Replace straight quotes with smart quotes which look better and don't break HTML
+    const safeContent = content.replace(/"/g, '"'); // Replace " with smart quote
+    return `${attrName}="${safeContent}"`;
+  } else if (hasDoubleQuotes) {
+    // Use single quotes for attribute
+    return `${attrName}='${content}'`;
+  } else {
+    // Use double quotes (default)
+    return `${attrName}="${content}"`;
+  }
+}
+
 // Generate meta tags
 function generateMetaTags(route, config, urlPath) {
   const tags = [];
@@ -843,17 +1008,21 @@ function generateMetaTags(route, config, urlPath) {
   tags.push(`<link rel="canonical" href="${canonicalUrl}">`);
 
   if (route.description) {
-    tags.push(`<meta name="description" content="${route.description}">`);
+    tags.push(
+      `<meta name="description" ${formatMetaAttribute("content", route.description)}>`
+    );
   }
 
   // Open Graph tags
   if (route.title) {
-    tags.push(`<meta property="og:title" content="${route.title}">`);
+    tags.push(
+      `<meta property="og:title" ${formatMetaAttribute("content", route.title)}>`
+    );
   }
 
   if (route.description) {
     tags.push(
-      `<meta property="og:description" content="${route.description}">`
+      `<meta property="og:description" ${formatMetaAttribute("content", route.description)}>`
     );
   }
 
@@ -876,7 +1045,7 @@ function generateMetaTags(route, config, urlPath) {
       const tagName = tag.tag || "meta";
       const attrs = Object.entries(tag)
         .filter(([key]) => key !== "tag" && key !== "soft")
-        .map(([key, value]) => `${key}="${value}"`)
+        .map(([key, value]) => formatMetaAttribute(key, value))
         .join(" ");
 
       if (attrs) {
@@ -894,7 +1063,10 @@ async function generate404Page({ template, outputDir, config, render }) {
 
   try {
     // Render a non-existent route to get the notFoundTemplate content
-    const renderResult = render("/this-route-does-not-exist-404");
+    const renderResult = render(
+      "/this-route-does-not-exist-404",
+      config.baseUrl
+    );
 
     // The render function will return the notFoundTemplate HTML
     const renderedHTML = renderResult.html || "404 - Page Not Found";
@@ -934,11 +1106,9 @@ async function generate404Page({ template, outputDir, config, render }) {
     html = html.replace("</head>", `  ${metaTags.join("\n")}\n  </head>`);
 
     // Replace root div content with rendered HTML
-    if (html.includes('<div id="root">')) {
-      html = html.replace(
-        /<div id="root">.*?<\/div>/s,
-        `<div id="root">${renderedHTML}</div>`
-      );
+    const rootDivRegex = /(<div[^>]*\sid=["']root["'][^>]*>)(.*?)(<\/div>)/is;
+    if (rootDivRegex.test(html)) {
+      html = html.replace(rootDivRegex, `$1${renderedHTML}$3`);
     } else {
       console.warn(
         '[Routerino Forge] Could not find <div id="root"> for 404.html'