create-react-adam 0.3.0 → 0.4.0

package/README.md

@@ -62,7 +62,10 @@ Every generated project starts with:
 
 - **Self-hosted Inter font** - variable `woff2` served from `public/fonts/`
   with `font-display: swap` and a preload hint; no third-party font requests
-- **Route-level code splitting** - pages load via `React.lazy` + `Suspense`
+- **Route-level code splitting with preloading** - pages load via
+  `React.lazy` + `Suspense`; chunks preload on link hover/focus/touch and an
+  idle prefetcher warms the rest after first paint (documented in the
+  generated README, easy to remove)
 - **SEO-ready `index.html`** - meta description, Open Graph and Twitter card
   tags, theme-color, plus a `public/robots.txt`
 - **Accessible shell** - skip-to-content link, `<main>` landmark, visible

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-react-adam",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Create opinionated React apps with TypeScript, Vite, Wouter, and Tailwind CSS",
   "type": "module",
   "bin": {

package/template/README.md

@@ -53,10 +53,11 @@ Vite dev server is running, and prints diagnostic information.
 ```
 src/
 ├── pages/          # Route pages (Home, About, NotFound)
-├── components/     # Reusable components
+├── components/     # Reusable components (Button, PreloadLink)
 ├── types/          # Shared TypeScript types
 ├── utils/          # Utility functions (if included)
 ├── App.tsx         # Routing, skip link, <main> landmark
+├── routes.ts       # Route import map + preload helpers
 ├── main.tsx        # Entry point
 └── app.css         # Tailwind theme + base styles
 ```
@@ -67,15 +68,55 @@ code-split with `React.lazy`, and each page sets its own `document.title`.
 ## Adding New Pages
 
 1. Create a new component in `src/pages/`
-2. Add a lazy import and route in `src/App.tsx`
+2. Add its import thunk to `src/routes.ts` (this both registers it for
+   preloading and gives `App.tsx` its lazy import)
+3. Add a lazy component and route in `src/App.tsx`
 
 ```tsx
-const NewPage = lazy(() => import("./pages/NewPage"));
+// src/routes.ts
+export const routeImports: Record<string, PageLoader> = {
+  // ...
+  "/new": () => import("./pages/NewPage"),
+};
+
+// src/App.tsx
+const NewPage = lazy(routeImports["/new"]);
 
 // In the Switch component:
 <Route path="/new" component={NewPage} />;
 ```
 
+4. Link to it with `<PreloadLink href="/new">` so the chunk preloads on
+   hover/focus/touch (wouter's plain `<Link>` works too, just without the
+   preload).
+
+## Route Preloading
+
+Pages are lazy-loaded, so without preloading every navigation waits for a
+network round trip. The template closes that gap in three layers:
+
+1. **One import map** (`src/routes.ts`): the router and the preloaders share
+   the same import thunks, and dynamic imports dedupe by module — so a
+   preloaded chunk is never downloaded twice.
+2. **Preload on intent** (`src/components/PreloadLink.tsx`): links fire the
+   target page's import on hover, focus, or touch. Hover-to-click is
+   typically 200-400ms — usually enough for the chunk to arrive first.
+3. **Idle backstop** (`preloadAllRoutesWhenIdle` in `src/routes.ts`, called
+   from `App.tsx`): after the window `load` event, remaining chunks are
+   fetched one at a time during idle periods. It never competes with
+   first-paint resources (so Lighthouse is unaffected) and skips users on
+   data-saver or 2G connections.
+
+`App.tsx` also routes against a `useDeferredValue`-deferred location, so the
+previous page stays painted until the next page is ready instead of flashing
+the blank `Suspense` fallback. Preloading makes navigation fast; the deferred
+location makes it smooth.
+
+**To remove preloading**, follow the steps in the header comment of
+`src/routes.ts` — in short: inline the imports back into `lazy()` in
+`App.tsx`, swap `<PreloadLink>` back to wouter's `<Link>`, and delete
+`src/routes.ts` and `src/components/PreloadLink.tsx`.
+
 ## Performance, SEO, and Accessibility
 
 - **Fonts**: Inter is self-hosted from `public/fonts/` (variable `woff2`,
@@ -95,7 +136,7 @@ and string literals. Convert images to WebP at
 For the rare image that must stay in another format:
 
 ```tsx
-// eslint-disable-next-line adam/prefer-webp-images
+// eslint-disable-next-line adamjsturge/prefer-webp-images
 import legacyLogo from "./legacy-logo.png";
 ```
 

package/template/eslint.config.js

@@ -8,7 +8,7 @@ import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
 import unicorn from "eslint-plugin-unicorn";
 import tseslint from "typescript-eslint";
-import adam from "./eslint-rules/prefer-webp-images.js";
+import adamjsturge from "./eslint-rules/prefer-webp-images.js";
 
 export default tseslint.config({
   extends: [
@@ -26,7 +26,7 @@ export default tseslint.config({
     "jsx-a11y": jsxA11y,
     "react-hooks": reactHooks,
     "react-refresh": reactRefresh,
-    adam,
+    adamjsturge,
   },
   languageOptions: {
     parserOptions: {
@@ -50,7 +50,7 @@ export default tseslint.config({
       "warn",
       { allowConstantExport: true },
     ],
-    "adam/prefer-webp-images": "error",
+    "adamjsturge/prefer-webp-images": "error",
   },
   files: ["**/*.{ts,tsx}"],
   ignores: ["dist"],

package/template/src/App.tsx

@@ -1,31 +1,51 @@
-import { lazy, Suspense } from "react";
-import { Redirect, Route, Switch } from "wouter";
+import { lazy, Suspense, useDeferredValue, useEffect } from "react";
+import { Redirect, Route, Switch, useLocation } from "wouter";
+import { preloadAllRoutesWhenIdle, routeImports } from "./routes";
 
-const Home = lazy(() => import("./pages/Home"));
-const About = lazy(() => import("./pages/About"));
-const NotFound = lazy(() => import("./pages/NotFound"));
+// Pages are code-split: each chunk downloads on demand. The import thunks
+// live in src/routes.ts so the preload helpers can warm the same chunks
+// ahead of navigation (routes.ts documents how it works and how to remove).
+const Home = lazy(routeImports["/"]);
+const About = lazy(routeImports["/about"]);
+const NotFound = lazy(routeImports["/404"]);
 
-const App = () => (
-  <>
-    <a
-      href="#main-content"
-      className="bg-brand-primary text-brand-white sr-only z-50 rounded-lg px-4 py-2 focus:not-sr-only focus:fixed focus:top-4 focus:left-4"
-    >
-      Skip to main content
-    </a>
-    <main id="main-content">
-      <Suspense fallback={null}>
-        <Switch>
-          <Route path="/" component={Home} />
-          <Route path="/about" component={About} />
-          <Route path="/home">
-            <Redirect to="/" />
-          </Route>
-          <Route component={NotFound} />
-        </Switch>
-      </Suspense>
-    </main>
-  </>
-);
+const App = () => {
+  const [location] = useLocation();
+  // Routing against a deferred location means React keeps the previous page
+  // painted while the next page's chunk loads and initializes, instead of
+  // flashing the blank Suspense fallback. Preloading makes navigation fast;
+  // this makes it smooth. To remove: pass nothing to <Switch> below and
+  // delete these two hook calls.
+  const deferredLocation = useDeferredValue(location);
+
+  // Idle backstop — quietly fetch all remaining page chunks once the page
+  // has fully loaded. Delete this effect to remove (see src/routes.ts).
+  useEffect(() => {
+    preloadAllRoutesWhenIdle();
+  }, []);
+
+  return (
+    <>
+      <a
+        href="#main-content"
+        className="bg-brand-primary text-brand-white sr-only z-50 rounded-lg px-4 py-2 focus:not-sr-only focus:fixed focus:top-4 focus:left-4"
+      >
+        Skip to main content
+      </a>
+      <main id="main-content">
+        <Suspense fallback={null}>
+          <Switch location={deferredLocation}>
+            <Route path="/" component={Home} />
+            <Route path="/about" component={About} />
+            <Route path="/home">
+              <Redirect to="/" />
+            </Route>
+            <Route component={NotFound} />
+          </Switch>
+        </Suspense>
+      </main>
+    </>
+  );
+};
 
 export default App;

package/template/src/components/PreloadLink.tsx

@@ -0,0 +1,49 @@
+import type { ComponentProps, FocusEvent, MouseEvent, TouchEvent } from "react";
+import { Link } from "wouter";
+import { preloadRoute } from "../routes";
+
+// Drop-in replacement for wouter's <Link> that preloads the target page's
+// chunk as soon as the user shows intent to navigate (hover, keyboard focus,
+// or touch). By the time the click lands, the chunk is usually in flight or
+// already cached, so navigation feels instant. See src/routes.ts for the
+// full preloading picture.
+//
+// HOW TO REMOVE: swap <PreloadLink> back to wouter's <Link> wherever it is
+// used (the props are identical), delete this file, and follow the removal
+// steps in src/routes.ts.
+
+// Mirrors wouter's <Link> props in its plain-anchor form. wouter's asChild
+// variant and `to` alias are not supported here — use wouter's <Link>
+// directly if you need those.
+type PreloadLinkProps = Omit<ComponentProps<"a">, "className" | "href"> & {
+  href: string;
+  className?: string | ((isActive: boolean) => string | undefined);
+  replace?: boolean;
+  state?: unknown;
+};
+
+const PreloadLink = (props: PreloadLinkProps) => {
+  const handleIntent = () => {
+    preloadRoute(props.href);
+  };
+
+  return (
+    <Link
+      {...props}
+      onMouseEnter={(event: MouseEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onMouseEnter?.(event);
+      }}
+      onFocus={(event: FocusEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onFocus?.(event);
+      }}
+      onTouchStart={(event: TouchEvent<HTMLAnchorElement>) => {
+        handleIntent();
+        props.onTouchStart?.(event);
+      }}
+    />
+  );
+};
+
+export default PreloadLink;

package/template/src/pages/About/index.no-utils.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { Link } from "wouter";
+import PreloadLink from "../../components/PreloadLink";
 
 const About = () => {
   useEffect(() => {
@@ -30,12 +30,12 @@ const About = () => {
           </ul>
         </div>
 
-        <Link
+        <PreloadLink
           href="/"
           className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
         >
           Back to Home
-        </Link>
+        </PreloadLink>
       </div>
     </div>
   );

package/template/src/pages/About/index.tsx

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
-import { Link } from "wouter";
 import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 import { useReactPersist } from "../../utils/Storage";
 import { useUrlState } from "../../utils/useUrlState";
 
@@ -93,12 +93,12 @@ const About = () => {
             <li>✨ ESLint & Prettier configured</li>
           </ul>
         </div>
-        <Link
+        <PreloadLink
           href="/"
           className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
         >
           Back to Home
-        </Link>
+        </PreloadLink>
       </div>
     </div>
   );

package/template/src/pages/Home/index.no-utils.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
-import { Link } from "wouter";
 import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 
 const Home = () => {
   const [count, setCount] = useState(0);
@@ -66,12 +66,12 @@ const Home = () => {
         </div>
 
         <div className="flex justify-center gap-4">
-          <Link
+          <PreloadLink
             href="/about"
             className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
           >
             About Page
-          </Link>
+          </PreloadLink>
           <a
             href="https://react.dev"
             target="_blank"

package/template/src/pages/Home/index.tsx

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
-import { Link } from "wouter";
 import Button from "../../components/Button";
+import PreloadLink from "../../components/PreloadLink";
 import { useReactPersist } from "../../utils/Storage";
 import { useUrlState } from "../../utils/useUrlState";
 
@@ -81,12 +81,12 @@ const Home = () => {
         </div>
 
         <div className="flex justify-center gap-4">
-          <Link
+          <PreloadLink
             href="/about"
             className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover rounded-lg px-6 py-3 transition-colors"
           >
             About Page
-          </Link>
+          </PreloadLink>
           <a
             href="https://react.dev"
             target="_blank"

package/template/src/pages/NotFound/index.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from "react";
-import { Link } from "wouter";
+import PreloadLink from "../../components/PreloadLink";
 
 const NotFound = () => {
   useEffect(() => {
@@ -16,12 +16,12 @@ const NotFound = () => {
         <p className="text-brand-gray mt-2">
           The page you're looking for doesn't exist.
         </p>
-        <Link
+        <PreloadLink
           href="/"
           className="bg-brand-primary text-brand-white hover:bg-brand-primaryHover mt-6 inline-block rounded-lg px-6 py-3 transition-colors"
         >
           Go Home
-        </Link>
+        </PreloadLink>
       </div>
     </div>
   );

package/template/src/routes.ts

@@ -0,0 +1,94 @@
+import type { ComponentType } from "react";
+
+// Route-level code splitting + preloading.
+//
+// This file is the single source of truth for every page's dynamic import.
+// App.tsx feeds these thunks to React.lazy() for routing, and the preload
+// helpers below fire the same thunks ahead of navigation. Because dynamic
+// imports are deduped by module, a preloaded chunk is never downloaded
+// twice — navigating just picks up the in-flight or already-cached module.
+//
+// Preloading happens in two layers:
+//   1. Intent: <PreloadLink> (src/components/PreloadLink.tsx) calls
+//      preloadRoute() on hover/focus/touch. Hover-to-click is typically
+//      200-400ms — enough for a small page chunk to arrive before the click.
+//   2. Idle backstop: preloadAllRoutesWhenIdle() (called once from App.tsx)
+//      fetches every remaining chunk after the window `load` event, one at a
+//      time during idle periods, so it never competes with first-paint
+//      resources (or your Lighthouse score).
+//
+// HOW TO REMOVE PRELOADING:
+//   1. In App.tsx: delete the preloadAllRoutesWhenIdle() effect and the
+//      useDeferredValue lines, and inline the imports back into lazy(),
+//      e.g. const Home = lazy(() => import("./pages/Home"));
+//   2. In src/pages/: replace <PreloadLink> with wouter's <Link>.
+//   3. Delete this file and src/components/PreloadLink.tsx.
+
+type PageLoader = () => Promise<{ default: ComponentType }>;
+
+export const routeImports: Record<string, PageLoader> = {
+  "/": () => import("./pages/Home"),
+  "/about": () => import("./pages/About"),
+  // Not a real link target — keyed by a pseudo-path so the idle prefetcher
+  // warms the 404 page too.
+  "/404": () => import("./pages/NotFound"),
+};
+
+// Fires a route's import ahead of navigation. Safe to call repeatedly and
+// with paths that are not in the map (external links, dynamic segments) —
+// those are a no-op.
+export function preloadRoute(path: string): void {
+  const load = routeImports[path];
+  if (!load) return;
+  load().catch(() => {
+    // Preloading is opportunistic: if it fails (offline, a deploy replaced
+    // the chunk), the real import on navigation will surface the error.
+  });
+}
+
+let hasStartedIdlePreload = false;
+
+// Fetches every route chunk after the page has fully loaded, one chunk at a
+// time during browser idle periods. Skips entirely for users on data-saver
+// or 2G connections.
+export function preloadAllRoutesWhenIdle(): void {
+  // React StrictMode runs effects twice in development — only start once.
+  if (hasStartedIdlePreload) return;
+  hasStartedIdlePreload = true;
+
+  const { connection } = navigator as Navigator & {
+    connection?: { saveData?: boolean; effectiveType?: string };
+  };
+  if (connection?.saveData === true) return;
+  if (connection?.effectiveType?.endsWith("2g") === true) return;
+
+  // Safari has no requestIdleCallback; a timeout is a close-enough stand-in.
+  const scheduleIdle = (callback: () => void): void => {
+    if (typeof window.requestIdleCallback === "function") {
+      window.requestIdleCallback(callback);
+    } else {
+      window.setTimeout(callback, 1500);
+    }
+  };
+
+  const queue = Object.values(routeImports);
+  const loadNext = async (): Promise<void> => {
+    const load = queue.shift();
+    if (!load) return;
+    try {
+      await load();
+    } catch {
+      // Ignore failures here for the same reason as preloadRoute.
+    }
+    scheduleIdle(() => void loadNext());
+  };
+
+  // Waiting for `load` keeps prefetching out of the critical path: every
+  // first-paint resource is done before the first idle callback runs.
+  const start = (): void => scheduleIdle(() => void loadNext());
+  if (document.readyState === "complete") {
+    start();
+  } else {
+    window.addEventListener("load", start, { once: true });
+  }
+}