routerino 2.6.1 → 2.6.2

package/docs/README.md

@@ -0,0 +1,8 @@
+# Routerino Documentation
+
+- [Getting Started](./getting-started.md) — New project setup, full React example
+- [SEO Guide](./seo-guide.md) — Page titles, canonical URLs, social previews, meta descriptions, hash links, structured data
+- [Image Optimization](./image-optimization.md) — Delegating image optimization to `vite-plugin-image-optimizer`
+- [Accessibility](./accessibility.md) — ESLint a11y setup, best practices for Lighthouse scores
+- [Vendoring](./vendoring.md) — Including Routerino directly in your project
+- [Additional Resources](./additional-resources.md) — External links for further reading

package/docs/accessibility.md

@@ -0,0 +1,87 @@
+# Accessibility & Lighthouse Scores
+
+To maximize your PageSpeed Insights and Lighthouse scores, set up ESLint with accessibility rules.
+
+## Setting up eslint-plugin-jsx-a11y
+
+1. Install the plugin:
+
+```sh
+npm install --save-dev eslint-plugin-jsx-a11y
+```
+
+2. Add to your ESLint config:
+
+```js
+// eslint.config.js (ESLint 9+ flat config)
+import jsxA11y from "eslint-plugin-jsx-a11y";
+
+export default [
+  {
+    plugins: {
+      "jsx-a11y": jsxA11y,
+    },
+    rules: {
+      ...jsxA11y.configs.recommended.rules,
+    },
+  },
+];
+```
+
+3. Add a lint run script:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint --ext .jsx,.js src/"
+  }
+}
+```
+
+## Key Rules
+
+### Images: Include descriptive `alt` text
+
+```jsx
+// Bad - Missing alt text
+<img src="/logo.png" />
+
+// Good - Descriptive alt text
+<img src="/logo.png" alt="Company logo" />
+
+// Good - Decorative images
+<img src="/decoration.png" alt="" role="presentation" />
+```
+
+### Heading Hierarchy: Use proper heading order
+
+```jsx
+// Bad - Skipping heading levels
+<h1>Page Title</h1>
+<h3>Subsection</h3>  // Should be h2
+
+// Good - Proper hierarchy
+<h1>Page Title</h1>
+<h2>Main Section</h2>
+<h3>Subsection</h3>
+```
+
+### Link Text: Avoid generic link text
+
+```jsx
+// Bad - Generic text
+<a href="/products">Click here</a>
+
+// Good - Descriptive text
+<a href="/products">View our products</a>
+```
+
+### ARIA Labels: Use for icon-only buttons
+
+```jsx
+<button aria-label="Close dialog">
+  <svg>...</svg>
+</button>
+```
+
+See [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) for more info.

package/docs/additional-resources.md

@@ -0,0 +1,6 @@
+# Additional Resources
+
+- [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)

package/docs/getting-started.md

@@ -0,0 +1,134 @@
+# Getting Started with Routerino
+
+## Starting a New React Project
+
+If you're starting from scratch, here's the recommended approach:
+
+1. Ensure you have [Node.js](https://nodejs.org/) and npm installed. Consider using a Node version manager like [Volta](https://volta.sh/), [fnm](https://github.com/Schniz/fnm), or [asdf](https://asdf-vm.com/).
+
+2. Create a new React project with [Vite](https://vitejs.dev/):
+
+```sh
+npm create vite@latest my-react-app -- --template react
+```
+
+3. Install dependencies:
+
+```sh
+cd my-react-app
+npm install
+```
+
+4. Add Routerino:
+
+```sh
+npm install routerino
+```
+
+## Full React Example
+
+This example includes the full React configuration. It can replace `src/main.jsx`:
+
+```jsx
+import React from "react";
+import { createRoot } from "react-dom/client";
+import Routerino from "routerino";
+
+export 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.",
+  },
+];
+
+const App = () => (
+  <main>
+    <nav>
+      <a href="/">Home</a>
+    </nav>
+
+    <Routerino
+      title="Example.com"
+      notFoundTitle="Sorry, but this page does not exist."
+      errorTitle="Yikes! Something went wrong."
+      routes={routes}
+    />
+
+    <footer>
+      <p>
+        Learn more <a href="/about/">about us</a> or{" "}
+        <a href="/contact/">contact us</a> today.
+      </p>
+    </footer>
+  </main>
+);
+
+createRoot(document.getElementById("root")).render(<App />);
+```
+
+## Using Preact
+
+Routerino is fully compatible with Preact via `@preact/compat`:
+
+1. Install Preact:
+
+```sh
+npm i preact @preact/compat
+```
+
+2. Configure your bundler:
+
+**Vite:**
+
+```js
+import { defineConfig } from "vite";
+import preact from "@preact/preset-vite";
+
+export default defineConfig({
+  plugins: [preact()],
+  resolve: {
+    alias: {
+      react: "@preact/compat",
+      "react-dom": "@preact/compat",
+      "react/jsx-runtime": "@preact/compat/jsx-runtime",
+    },
+  },
+});
+```
+
+**Webpack:**
+
+```js
+module.exports = {
+  resolve: {
+    alias: {
+      react: "preact/compat",
+      "react-dom": "preact/compat",
+    },
+  },
+};
+```
+
+3. Use Routerino exactly as you would in a React project — the API is identical.

package/docs/image-optimization.md

@@ -0,0 +1,30 @@
+# Image Optimization
+
+Routerino delegates image optimization to [`vite-plugin-image-optimizer`](https://github.com/FatehAK/vite-plugin-image-optimizer). Install it along with `sharp` and add it to your Vite config **before** `routerinoForge`:
+
+```sh
+npm install --save-dev vite-plugin-image-optimizer sharp
+```
+
+```js
+// vite.config.js
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { ViteImageOptimizer } from "vite-plugin-image-optimizer";
+import { routerinoForge } from "routerino/forge";
+
+export default defineConfig({
+  plugins: [
+    react(),
+    ViteImageOptimizer({
+      jpg: { quality: 80 },
+      jpeg: { quality: 80 },
+      png: { quality: 80 },
+      webp: { quality: 80 },
+    }),
+    routerinoForge({ baseUrl: "https://example.com" }),
+  ],
+});
+```
+
+Use standard HTML `<img>` tags in your components — the plugin optimizes source images in `public/` and imported assets during the Vite build. No special component or props needed.

package/docs/seo-guide.md

@@ -0,0 +1,137 @@
+# SEO Guide
+
+## Page Titles
+
+- Keep page titles unique for each route. Avoid including the site name like "Foo.com" in individual page titles — Routerino adds that automatically.
+- Aim for concise, descriptive titles that accurately represent the page content.
+- Keep title length at a max of 50-60 characters. Longer text may be ignored or cut off, especially on mobile.
+
+## URL Structure & Canonicalization
+
+When multiple URLs show the same content (like `/about` vs `/about/`), search engines need to know which one is the "official" version to avoid duplicate content penalties. Routerino handles this automatically.
+
+**With SSG:** Creates both `/about.html` and `/about/index.html` with canonical tags:
+
+```html
+<link rel="canonical" href="https://example.com/about/" />
+<meta property="og:url" content="https://example.com/about/" />
+```
+
+**With Prerender (SPA):** Includes meta tags for correct status codes:
+
+```html
+<!-- For canonical URL (/about/) -->
+<link rel="canonical" href="https://example.com/about/" />
+<meta property="og:url" content="https://example.com/about/" />
+
+<!-- For non-canonical URL (/about) -->
+<meta name="prerender-status-code" content="301" />
+<meta name="prerender-header" content="Location: https://example.com/about/" />
+```
+
+Use `useTrailingSlash={false}` if you prefer URLs without trailing slashes. Use `baseUrl` if your site is served from multiple domains:
+
+```jsx
+<Routerino baseUrl="https://example.com" routes={routes} />
+```
+
+## Social Previews & Open Graph
+
+Routerino automatically sets core Open Graph tags (`og:title`, `og:description`, `og:url`, `og:image`) for every page.
+
+### Image Best Practices
+
+- Size: Use 1200x630 pixels (1.91:1 ratio) for maximum compatibility
+- Add dimensions for faster first-share rendering:
+
+```js
+updateHeadTag({ property: "og:image:width", content: "1200" });
+updateHeadTag({ property: "og:image:height", content: "630" });
+```
+
+### Branding
+
+For site-wide branding, add `og:site_name`:
+
+```js
+updateHeadTag({ property: "og:site_name", content: "Your Brand" });
+```
+
+### Platform-Specific Enhancements
+
+- Apple/iMessage: Set `touchIconUrl` prop for iMessage link previews
+- Video content:
+
+```js
+updateHeadTag({
+  property: "og:video",
+  content: "https://example.com/video.mp4",
+});
+updateHeadTag({ property: "og:video:type", content: "video/mp4" });
+```
+
+### Testing Previews
+
+Test how your links appear with platform-specific tools (platforms cache aggressively — use these to force a refresh):
+
+- [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/)
+- [LinkedIn Post Inspector](https://www.linkedin.com/post-inspector/)
+- [Twitter Card Validator](https://cards-dev.twitter.com/validator)
+
+### Twitter Cards
+
+Routerino automatically includes `summary_large_image` for maximum engagement:
+
+```html
+<meta name="twitter:card" content="summary_large_image" />
+```
+
+## Meta Descriptions
+
+- Provide unique, informative descriptions for each route.
+- Keep them under ~150 characters to avoid truncation in search results.
+
+## Structured Data (JSON-LD)
+
+Use the `innerHTML` property on a `<script type="application/ld+json">` head tag:
+
+```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 SSG (via the forge plugin).
+
+## 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.
+
+**Sticky headers:** Use [`scroll-margin-top`](https://developer.mozilla.org/en-US/docs/Web/CSS/scroll-margin-top) to offset the scroll target:
+
+```css
+[id] {
+  scroll-margin-top: 80px; /* match your header height */
+}
+```
+
+This works for SPA navigation, native browser hash navigation, and direct page loads.
+
+## 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.
+- Ensure your site is mobile-friendly and loads quickly.

package/docs/vendoring.md

@@ -0,0 +1,30 @@
+# Vendoring Routerino
+
+If you prefer to include Routerino directly in your project instead of using it as a dependency, you can vendor the library. This gives you full control over the version and eliminates managing it as an external dependency.
+
+1. Download `routerino.jsx` from the [repository](../routerino.jsx).
+
+2. Place it in a suitable location within your project:
+
+```
+your-project/
+├── src/
+│   ├── vendor/
+│   │   └── routerino.jsx
+│   └── ...
+└── ...
+```
+
+3. Update your imports:
+
+```jsx
+// Before (importing from the package)
+import Routerino from "routerino";
+
+// After (importing from the vendored file)
+import Routerino from "./vendor/routerino";
+```
+
+4. If using the Routerino Forge plugin for SSG and sitemap generation, copy `routerino-forge.js` as well.
+
+**Note:** When vendoring, you'll need to manually update the vendored files to incorporate future updates or bug fixes from the main repository.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "routerino",
-  "version": "2.6.1",
-  "description": "A lightweight, SEO-optimized React router for modern web applications",
+  "version": "2.6.2",
+  "description": "The React router that Google can read. Built-in SSG, meta tags, sitemaps, and canonical URLs — zero dependencies, no framework lock-in.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nerds-with-keyboards/routerino.git"
@@ -11,7 +11,17 @@
     "react",
     "seo",
     "prerender",
-    "react router"
+    "ssg",
+    "static-site",
+    "static-site-generator",
+    "vite",
+    "vite-plugin",
+    "meta-tags",
+    "open-graph",
+    "sitemap",
+    "seo-friendly",
+    "jamstack",
+    "zero-dependency"
   ],
   "license": "MIT",
   "bugs": {