routerino 1.1.10 → 2.0.0

package/README.md

@@ -2,13 +2,41 @@
 
 > A lightweight, SEO-optimized React router for modern websites and applications
 
-Routerino is a zero-dependency router tailored for [React](https://reactjs.org/) [client-side rendered (CSR)](https://developers.google.com/web/updates/2019/02/rendering-on-the-web#csr) websites - perfect for modern web architectures like [JAMStack](https://jamstack.org/) or simple [Vite.js](https://vitejs.dev/)-React sites. It supports [Prerender](https://github.com/prerender/prerender) tags for SEO-friendly redirects and HTTP status codes, and can **automatically generate a sitemap.xml** file from your routes. Routerino simplifies client-side routing in React apps while providing handy SEO optimizations out of the box - a **minimalist router with SEO benefits**.
-
-As a developer, I've always been passionate about creating user-friendly applications and websites. However, I've faced challenges in routing and SEO optimization for React client-side rendered (CSR) websites. For years, the de facto routing monoculture has stifled diversity and innovation in the React ecosystem. Moreover, keeping up with the frequent API churn has been time-consuming and frustrating. Driven by these challenges, I set out to create Routerino — a lightweight, zero-dependency router that simplifies routing and offers excellent SEO benefits.
-
-I also wanted the ability to steer clear of the JSX-soup that has become prevalent in the React ecosystem. HTML is a powerful tool and it's often enough. Attempts to abstract away the web browser have led to excessive complexity, an endless black hole of bugs, and poor developer experience and delivery speed. If you've encountered such issues, you know exactly what I mean. By using plain HTML in JSX, we can build applications with simplicity. We shouldn't use this as an excuse to introduce needless complexity.
-
-Here's a quick example of what using Routerino looks like:
+Routerino is a zero-dependency router for React (17/18/19) 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?
+
+- **SEO-First Design**: Automatic meta tag management, sitemap generation, and prerender support ensure maximum search engine visibility
+- **Zero Dependencies**: Keeps bundle size minimal and reduces supply-chain vulnerabilities
+- **Simple API**: No special `Link` components required - use standard HTML anchors and navigate programmatically with standard browser APIs
+- **Static Site Generation**: Build-tool agnostic static HTML generation for improved performance and SEO
+- **Production Ready**: Includes Docker-based prerender server for easy deployments
+- **Single File Core**: The entire routing logic fits in one file (~420 lines), making it easy to understand and customize
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Props](#props-arguments)
+  - [Get route parameters](#get-route-parameters-and-the-current-route-and-updating-head-tags)
+  - [updateHeadTag](#updateheadtag)
+- [Best Practices](#routerino-best-practices)
+- [Generating a Sitemap](#generating-a-sitemap-from-routes)
+- [Static Site Generation](#static-site-generation)
+- [Deployment Guides](#deployment-guides)
+- [Prerender Server (Docker)](#prerender-server-docker)
+- [How-to Guides & Examples](#how-to-guides--example-code)
+  - [Starting a New Project](#starting-a-new-react-project-with-routerino)
+  - [Full React Example](#full-react-example)
+  - [Basic Example](#basic-example)
+- [ErrorBoundary Component](#errorboundary-component)
+- [Vendoring Routerino](#vendoring-routerino)
+- [Additional Resources](#additional-resources)
+- [Contributions](#contributions)
+- [License](#license)
+
+## Quick Start
 
 ```jsx
 <Routerino
@@ -36,36 +64,28 @@ Here's a quick example of what using Routerino looks like:
 />
 ```
 
-For more details on getting started, see the [Installation](#installation) and [Usage](#usage) sections below.
+This simple configuration automatically handles routing, meta tags, and SEO optimization for your React application.
 
 ## Features
 
-Routerino empowers developers to define and manage routing and SEO concerns in one centralized location. This approach eliminates duplication when creating sitemaps and setting page metadata, such as descriptions or open-graph tags. The core of Routerino fits in a single file, making it [easy to vendor](#vendoring-routerino) if that suits your needs.
-
-Key capabilities:
-
 - Routing
-
-  - Easy integration of simple routing for your React app (supports React v18, older versions have not yet been tested)
+  - Easy integration of simple routing for your React app (supports React versions 17, 18, and 19)
   - Zero dependencies for lighter, more maintainable projects
   - No special link components required, works great for Markdown-based pages and semantic HTML
 
 - SEO Optimization
-
   - Configure title, description, and image for each route
   - Set `<head>` tags for any route (either directly in your routes config, or dynamically after rendering)
   - Set a site-wide name to be included with page titles
   - Automatically generate and maintain an up-to-date `sitemap.xml` from your routes
+  - Generate static HTML files for each route with proper meta tags
   - Implement SEO best practices out-of-the-box
   - Optimize for Googlebot with pre-rendering support
 
 - Enhanced User Experience
-
   - Support for sharing and social preview metadata
   - Snappy page transitions with automatic scroll reset, eliminating the jarring experience of landing mid-page when navigating
 
-Routerino is designed to work with modern browsers and has been tested with the latest versions of Chrome, Firefox, Safari, and Edge.
-
 ## Installation
 
 Ensure that you have React and React DOM installed in your project as peer dependencies. To add as a dev dependency:
@@ -77,9 +97,10 @@ npm i routerino -D
 ### Compatibility
 
 Routerino supports:
+
 - **React 17, 18, and 19** - All versions are tested and supported
-- **Preact** - Compatible via `@preact/compat`
-- **Node.js 18+** - Tested on Node.js 18, 20, and 22
+- **Preact** - Compatible via `@preact/compat` (needs verification)
+- **Node.js 18+** - Tested on Node.js 18, 20, 22, and 24. Could be used on earlier versions if we don't run tests.
 
 ## Usage
 
@@ -99,7 +120,7 @@ Here's a quick example of using Routerino in your React application:
 />
 ```
 
-Links are just regular HTML anchor tags. No need to use special `<Link>` components and you can handle styling however you wish. For example: `<a href="/some-page/>a link</a>`
+Links are just regular HTML anchor tags. No need to use special `<Link>` components and you can handle styling however you wish. For example: `<a href="/some-page/">a link</a>`
 
 See [props](#props-arguments) for full explanations and [example code](#how-to-guides--example-code) for more complete code samples.
 
@@ -145,7 +166,7 @@ See [RouteConfig props](#routeconfig-props) for more details. At a minimum a pat
 
 ##### `separator`: string;
 
-A string to separate the page title from the site title. The default is `|` (a pipe character w/space around). Set this to customize the separator.
+A string to separate the page title from the site title. The default is `" | "` (a pipe character w/space around). Set this to customize the separator.
 
 ##### `notFoundTemplate`: element;
 
@@ -412,11 +433,84 @@ Add `routerino-build-sitemap` to your build command to update automatically on e
 
 Example package.json build script: `"build": "vite build && routerino-build-sitemap routeFilePath=src/routes.jsx hostname=https://example.com outputDir=dist",`
 
+## Static Site Generation
+
+Routerino includes a build-tool agnostic static site generator that creates HTML files for each route, improving SEO and initial page load performance.
+
+### How It Works
+
+The `routerino-build-static` command is a **post-build step** that works with ANY build tool (Vite, Webpack, Parcel, etc.):
+
+1. **First**: Build your app with your preferred build tool (`npm run build`)
+2. **Then**: Run `routerino-build-static` to generate static HTML files
+
+```sh
+# After your build completes (creates dist/index.html with bundled JS/CSS):
+routerino-build-static routesFile=src/routes.jsx outputDir=dist template=dist/index.html baseUrl=https://example.com
+```
+
+**Parameters:**
+
+- `routesFile` - Path to your routes configuration file (supports .js, .jsx, .ts, .tsx)
+- `outputDir` - Directory where static HTML files will be generated (usually your build output)
+- `template` - Your **built** HTML file with bundled assets (e.g., dist/index.html)
+- `baseUrl` - Base URL for meta tags (optional but recommended for SEO)
+
+### Build Tool Examples
+
+Works with any build tool:
+
+```json
+// Vite
+"build": "vite build && routerino-build-static routesFile=src/routes.js outputDir=dist template=dist/index.html"
+
+// Webpack
+"build": "webpack && routerino-build-static routesFile=src/routes.js outputDir=build template=build/index.html"
+
+// Parcel
+"build": "parcel build index.html && routerino-build-static routesFile=src/routes.js outputDir=dist template=dist/index.html"
+```
+
+### What Gets Generated
+
+The static build process will:
+
+- Generate an HTML file for each non-dynamic route (routes with `:param` are skipped)
+- Apply route-specific meta tags (title, description, og:tags, custom tags)
+- Add proper `data-route` attributes for client-side hydration
+- Preserve your existing HTML structure and assets
+
+### Example Output
+
+For a route configuration like:
+
+```javascript
+{
+  path: '/about',
+  title: 'About Us',
+  description: 'Learn more about our company',
+  imageUrl: 'https://example.com/about-og.jpg'
+}
+```
+
+The generated `/about.html` will include:
+
+```html
+<title>About Us</title>
+<meta name="description" content="Learn more about our company" />
+<meta property="og:title" content="About Us" />
+<meta property="og:description" content="Learn more about our company" />
+<meta property="og:image" content="https://example.com/about-og.jpg" />
+<meta property="og:url" content="https://example.com/about" />
+```
+
+This provides excellent SEO while maintaining the benefits of a React SPA.
+
 ## How-to Guides & Example Code
 
 1. [Starting a New React Project with Routerino](#starting-a-new-react-project-with-routerino)
-2. [Basic Example](#basic-example)
-3. [Full React Example](#full-react-example)
+2. [Full React Example](#full-react-example)
+3. [Basic Example](#basic-example)
 
 ### Starting a New React Project with Routerino
 
@@ -464,40 +558,15 @@ This command will install the latest version of Routerino and save it to your `p
 
 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.
 
-### Basic Example
+### Full React Example
 
-Somewhere in your project, such as in your `src/App.jsx` file, import Routerino and add it to your code. Define your routes and configure the site title.
+This example includes the full React configuration. It might take the place of `src/main.jsx` or an `index.js` file.
 
 ```jsx
 import React from "react";
+import { render } from "react-dom";
 import Routerino from "routerino";
 
-// example pages
-import HomePage from "./HomePage";
-import AboutPage from "./AboutPage";
-import ContactPage from "./ContactPage";
-
-const routes = [
-  {
-    path: "/",
-    element: <HomePage />,
-    title: "Home",
-    description: "Welcome to my website!",
-  },
-  {
-    path: "/about/",
-    element: <AboutPage />,
-    title: "About",
-    description: "Learn more about us.",
-  },
-  {
-    path: "/contact/",
-    element: <ContactPage />,
-    title: "Contact",
-    description: "Get in touch with us.",
-  },
-];
-
 const App = () => (
   <main>
     <nav>
@@ -505,10 +574,37 @@ const App = () => (
     </nav>
 
     <Routerino
-      title="Foo.com"
-      routes={routes}
+      title="Example.com"
       notFoundTitle="Sorry, but this page does not exist."
       errorTitle="Yikes! Something went wrong."
+      routes={[
+        {
+          path: "/",
+          element: <p>Welcome to Home</p>,
+          title: "Home",
+          description: "Welcome to my website!",
+        },
+        {
+          path: "/about/",
+          element: <p>About us...</p>,
+          title: "About",
+          description: "Learn more about us.",
+        },
+        {
+          path: "/contact/",
+          element: (
+            <div>
+              <h1>Contact Us</h1>
+              <p>
+                Please <a href="mailto:user@example.com">send us an email</a> at
+                user@example.com
+              </p>
+            </div>
+          ),
+          title: "Contact",
+          description: "Get in touch with us.",
+        },
+      ]}
     />
 
     <footer>
@@ -520,72 +616,49 @@ const App = () => (
   </main>
 );
 
-export default App;
+render(<App />, document.getElementById("root"));
 ```
 
-### Full React Example
+## ErrorBoundary Component
 
-This example includes the full React configuration. It might take the place of `src/main.jsx` or an `index.js` file. Also suitable for use in a code-pen.
+Routerino exports an `ErrorBoundary` component that you can use in your own applications to catch and handle React component errors gracefully. Fun fact: error boundary components are one of the last cases that still require using a React Class! Since this library aims to include everything you need to build a multiple page React SPA, and enable users to be able to know which component had an issue without confusing it with a Routerino bug.
+
+### Import
 
 ```jsx
-import React from "react";
-import { render } from "react-dom";
-import Routerino from "routerino";
+import { ErrorBoundary } from "routerino";
+```
 
-const title = "Example.com";
-const routes = [
-  {
-    path: "/",
-    element: <p>Welcome to Home</p>,
-    title: "Home",
-    description: "Welcome to my website!",
-  },
-  {
-    path: "/about/",
-    element: <p>About us...</p>,
-    title: "About",
-    description: "Learn more about us.",
-  },
-  {
-    path: "/contact/",
-    element: (
-      <div>
-        <h1>Contact Us</h1>
-        <p>
-          Please <a href="mailto:user@example.com">send us an email</a> at
-          user@example.com
-        </p>
-      </div>
-    ),
-    title: "Contact",
-    description: "Get in touch with us.",
-  },
-];
+### Usage
 
-const App = () => (
-  <main>
-    <nav>
-      <a href="/">Home</a>
-    </nav>
+```jsx
+<ErrorBoundary
+  fallback={<div>Something went wrong. Please try again.</div>}
+  errorTitleString="Error | My Application"
+  usePrerenderTags={true}
+>
+  <MyComponent />
+</ErrorBoundary>
+```
 
-    <Routerino
-      {...{
-        title,
-        routes,
-      }}
-    />
+### Props
 
-    <footer>
-      <p>
-        Learn more <a href="/about/">about us</a> or{" "}
-        <a href="/contact/">contact us</a> today.
-      </p>
-    </footer>
-  </main>
-);
+| Prop               | Type        | Required | Description                                          |
+| ------------------ | ----------- | -------- | ---------------------------------------------------- |
+| `children`         | `ReactNode` | No       | The child components to render when there's no error |
+| `fallback`         | `ReactNode` | No       | The UI to display when an error is caught            |
+| `errorTitleString` | `string`    | Yes      | The document title to set when an error occurs       |
+| `usePrerenderTags` | `boolean`   | No       | Whether to set prerender meta tag (status code 500)  |
 
-render(<App />, document.getElementById("root"));
-```
+### Features
+
+- Catches JavaScript errors in child component tree
+- Displays fallback UI instead of white screen
+- Sets document title on error
+- Logs errors to console for debugging
+- Optionally sets prerender status code for SEO
+
+This is the same error boundary used internally by Routerino to protect your route components from crashing the entire application.
 
 ## Vendoring Routerino
 
@@ -624,7 +697,7 @@ By vendoring Routerino, you have full control over the code and can make any nec
 
 ## Additional Resources
 
-There is a lot of information on SEO and social previews. Here are some sources for further reading on best-practices.
+Here are some sources for further reading on SEO best-practices.
 
 - [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/)