create-react-adam 0.3.0 → 0.5.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.5.0",
   "description": "Create opinionated React apps with TypeScript, Vite, Wouter, and Tailwind CSS",
   "type": "module",
   "bin": {

package/template/.github/workflows/check.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

package/template/.github/workflows/e2e.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -36,7 +36,7 @@ jobs:
         run: npm run test:e2e
 
       - name: Upload Playwright report
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: playwright-report
@@ -44,7 +44,7 @@ jobs:
           retention-days: 30
 
       - name: Upload Allure results
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@v7
         if: always()
         with:
           name: allure-results

package/template/.github/workflows/lighthouse.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

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

@@ -1,14 +1,14 @@
 import eslint from "@eslint/js";
 import prettier from "eslint-config-prettier";
 import deMorgan from "eslint-plugin-de-morgan";
-import importPlugin from "eslint-plugin-import";
+import importPlugin from "eslint-plugin-import-x";
 import jsxA11y from "eslint-plugin-jsx-a11y";
 import promisePlugin from "eslint-plugin-promise";
 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/eslint.config.no-webp.js

@@ -1,7 +1,7 @@
 import eslint from "@eslint/js";
 import prettier from "eslint-config-prettier";
 import deMorgan from "eslint-plugin-de-morgan";
-import importPlugin from "eslint-plugin-import";
+import importPlugin from "eslint-plugin-import-x";
 import jsxA11y from "eslint-plugin-jsx-a11y";
 import promisePlugin from "eslint-plugin-promise";
 import reactHooks from "eslint-plugin-react-hooks";

package/template/package.json

@@ -25,26 +25,32 @@
     "wouter": "3.10.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.4",
+    "@eslint/js": "10.0.1",
     "@tailwindcss/vite": "4.3.2",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "5.2.0",
-    "eslint": "9.39.4",
+    "@vitejs/plugin-react": "6.0.3",
+    "eslint": "10.6.0",
     "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-typescript": "4.4.5",
     "eslint-plugin-de-morgan": "2.1.2",
-    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-import-x": "4.17.1",
     "eslint-plugin-jsx-a11y": "6.10.2",
     "eslint-plugin-promise": "7.3.0",
     "eslint-plugin-react-hooks": "7.1.1",
     "eslint-plugin-react-refresh": "0.5.3",
-    "eslint-plugin-unicorn": "62.0.0",
+    "eslint-plugin-unicorn": "71.1.0",
     "prettier": "3.9.5",
     "prettier-plugin-organize-imports": "4.3.0",
     "prettier-plugin-tailwindcss": "0.8.0",
     "tailwindcss": "4.3.2",
-    "typescript": "5.9.3",
+    "typescript": "6.0.3",
     "typescript-eslint": "8.63.0",
-    "vite": "7.3.6"
+    "vite": "8.1.4"
+  },
+  "overrides": {
+    "eslint-plugin-jsx-a11y": {
+      "eslint": "$eslint"
+    }
   }
 }

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,98 @@
+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;
+  void (async () => {
+    try {
+      await 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 globalThis.requestIdleCallback === "function") {
+      globalThis.requestIdleCallback(callback);
+    } else {
+      globalThis.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 });
+  }
+}

package/template/src/utils/useUrlState.ts

@@ -20,7 +20,7 @@ export function useUrlState(
   const urlValue = params.get(key);
   const value = urlValue
     ? typeof defaultValue === "number"
-      ? Number.parseInt(urlValue, 10)
+      ? Number(urlValue)
       : urlValue
     : defaultValue;
 

package/template/vite.config.ts

@@ -1,6 +1,4 @@
-// eslint-disable-next-line import/no-unresolved
 import tailwindcss from "@tailwindcss/vite";
-// eslint-disable-next-line import/no-unresolved
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";