create-react-adam 0.2.2 → 0.4.0

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

@@ -17,7 +17,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: "24.11.1"
+          node-version: "24.18.0"
           cache: "npm"
 
       - name: Install dependencies
@@ -36,7 +36,7 @@ jobs:
         run: npm run test:e2e
 
       - name: Upload Playwright report
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         if: always()
         with:
           name: playwright-report
@@ -44,7 +44,7 @@ jobs:
           retention-days: 30
 
       - name: Upload Allure results
-        uses: actions/upload-artifact@v5
+        uses: actions/upload-artifact@v6
         if: always()
         with:
           name: allure-results

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

@@ -0,0 +1,33 @@
+name: Lighthouse CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  lighthouse:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: "24.18.0"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Run Lighthouse CI
+        uses: treosh/lighthouse-ci-action@v12
+        with:
+          configPath: ./lighthouserc.json
+          uploadArtifacts: true

package/template/.nvmrc

@@ -1,2 +1,2 @@
-24.11.1
+24.18.0
 

package/template/README.md

@@ -1,6 +1,6 @@
-# **PROJECT_NAME**
+# {{PROJECT_NAME}}
 
-A React application created with create-react-adam.
+A React application created with [create-react-adam](https://github.com/adamjsturge/create-react-adam).
 
 ## Getting Started
 
@@ -12,14 +12,6 @@ This will start the development server at `http://localhost:5173`.
 
 ## Available Scripts
 
-### `npm run itDoesNotWork`
-
-Runs basic troubleshooting checks:
-
-- Installs dependencies
-- Checks if Vite dev server is running
-- Provides helpful diagnostic information
-
 ### `npm run dev`
 
 Starts the development server with hot module replacement.
@@ -32,49 +24,200 @@ Builds the app for production. The build artifacts will be stored in the `dist/`
 
 Previews the production build locally.
 
-### `npm run lint`
+### `npm run lint` / `npm run lint:check`
+
+Runs ESLint with auto-fix / check-only (for CI).
+
+### `npm run format` / `npm run format:check`
+
+Formats all files with Prettier (organizes imports, sorts Tailwind classes) / check-only (for CI).
+
+### `npm run setFormatToPrecommitHook`
 
-Runs ESLint to check for code quality issues.
+Installs a git pre-commit hook that formats and lints staged files. If this
+project was scaffolded outside an existing repository, the hook was already
+installed for you.
 
-### `npm run format`
+### `npm run test:e2e` (if E2E was included)
 
-Formats all files with Prettier, organizing imports and sorting Tailwind classes.
+Runs Playwright E2E tests from the `e2e/` directory. `test:e2e:ui` opens
+Playwright UI mode and `test:e2e:report` generates an Allure report.
 
-## Tech Stack
+### `npm run itDoesNotWork`
 
-- **React** - UI library
-- **TypeScript** - Type safety
-- **Vite** - Build tool and dev server
-- **Wouter** - Lightweight routing
-- **Tailwind CSS** - Utility-first CSS framework
-- **ESLint & Prettier** - Code quality and formatting
+Runs basic troubleshooting checks: installs dependencies, checks whether the
+Vite dev server is running, and prints diagnostic information.
 
 ## Project Structure
 
 ```
 src/
-  ├── pages/          # Page components
-  │   ├── Home/index.tsx
-  │   └── About/index.tsx
-  ├── App.tsx         # Main app with routes
-  ├── main.tsx        # Entry point
-  └── app.css         # Global styles (Tailwind imports)
+├── pages/          # Route pages (Home, About, NotFound)
+├── 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
 ```
 
+Routing uses [Wouter](https://github.com/molefrog/wouter). Pages are
+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. Import and add a route in `src/App.tsx`
-
-Example:
+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
-import NewPage from "./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`,
+  `font-display: swap`, preloaded in `index.html`). No third-party requests.
+- **SEO**: `index.html` ships meta description, Open Graph, and Twitter card
+  tags — update them as your app takes shape. `public/robots.txt` is included.
+- **Accessibility**: a skip-to-content link, `<main>` landmark, and visible
+  `:focus-visible` styles are wired into `App.tsx` / `app.css`.
+
+## ESLint: prefer-webp-images (if included)
+
+A local rule in `eslint-rules/prefer-webp-images.js` errors on references to
+`.png`, `.jpg`, `.jpeg`, `.gif`, or `.bmp` images in imports, JSX attributes,
+and string literals. Convert images to WebP at
+[tools.sturge.dev/webp](https://tools.sturge.dev/webp).
+
+For the rare image that must stay in another format:
+
+```tsx
+// eslint-disable-next-line adamjsturge/prefer-webp-images
+import legacyLogo from "./legacy-logo.png";
+```
+
+## Utilities (if included)
+
+### `classNames`
+
+Joins class names, skipping falsy values, with clsx-style conditional objects:
+
+```tsx
+import classNames from "./utils/classNames";
+
+classNames("btn", isActive && "btn-active", { hidden: !isOpen });
+// => "btn btn-active hidden" depending on the conditions
+```
+
+### `storage` and `useReactPersist`
+
+`localStorage` wrapper with JSON serialization and optional expiry, plus a
+`useState`-compatible hook that persists across reloads:
+
+```tsx
+import storage, { useReactPersist } from "./utils/Storage";
+
+storage.save("token", "abc123", { secondsTillExpiry: 3600 });
+storage.load("token", null);
+
+const [count, setCount] = useReactPersist("counter", 0);
+```
+
+### `useUrlState`
+
+`useState`-compatible hook that syncs a value with a URL query parameter.
+Supports string and number values (the type follows the default value):
+
+```tsx
+import { useUrlState } from "./utils/useUrlState";
+
+const [page, setPage] = useUrlState("page", 1);
+const [tab, setTab] = useUrlState("tab", "overview");
+```
+
+### `useInternetConnected`
+
+Runs a callback when the browser is online and every time the connection
+comes back:
+
+```tsx
+import { useInternetConnected } from "./utils/Internet";
+
+useInternetConnected(() => refetch(), [refetch]);
+```
+
+### `safeTimeout`
+
+Drop-in `setTimeout` replacement that clamps delays above the 32-bit signed
+integer maximum (~24.8 days) instead of letting them overflow and fire
+immediately:
+
+```tsx
+import { safeTimeout } from "./utils/helpers";
+
+safeTimeout(() => expireSession(), thirtyDaysInMs);
+```
+
+## CI Workflows
+
+- **Code Checks** (`.github/workflows/check.yml`): type checking, formatting,
+  linting, and a production build on every push and PR to `main`.
+- **E2E Tests** (`.github/workflows/e2e.yml`, if included): Playwright tests
+  with report artifacts.
+- **Lighthouse CI** (`.github/workflows/lighthouse.yml`, if included): audits
+  the production build and fails below accessibility ≥ 95, SEO ≥ 95, and
+  performance ≥ 85. Budgets live in `lighthouserc.json`.
+
+## Dependency Management
+
+Dependencies are pinned to exact versions and `.npmrc` sets
+`save-exact=true`, so future installs stay pinned. The repo is
+Renovate-friendly.
+
 ## Learn More
 
 - [React Documentation](https://react.dev)

package/template/e2e/gitignore

@@ -0,0 +1,13 @@
+# Dependencies
+node_modules
+
+# Test results
+test-results
+playwright-report
+allure-results
+allure-report
+playwright/.cache
+
+# Logs
+*.log
+

package/template/e2e/package.json

@@ -9,7 +9,7 @@
     "test:e2e:report": "allure generate ./allure-results --clean && allure open"
   },
   "devDependencies": {
-    "@playwright/test": "1.57.0",
-    "allure-playwright": "3.4.2"
+    "@playwright/test": "1.61.1",
+    "allure-playwright": "3.10.2"
   }
 }

package/template/eslint-rules/prefer-webp-images.js

@@ -0,0 +1,66 @@
+const NON_WEBP_IMAGE_PATTERN = /\.(png|jpe?g|gif|bmp)$/i;
+
+/**
+ * Flags references to non-WebP raster images (.png, .jpg, .jpeg, .gif, .bmp)
+ * in imports, JSX attributes, and string literals. WebP/AVIF/SVG are allowed.
+ */
+function findNonWebpImage(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  // Handle srcSet-style values ("a.png 1x, b.png 2x") and Vite suffixes
+  // ("./a.png?url") by checking each path-like token.
+  for (const token of value.split(/[\s,]+/)) {
+    const path = token.split(/[?#]/)[0];
+    if (NON_WEBP_IMAGE_PATTERN.test(path)) {
+      return token;
+    }
+  }
+
+  return null;
+}
+
+const preferWebpImages = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description:
+        "Prefer WebP images over PNG/JPEG/GIF/BMP for smaller file sizes and faster page loads",
+    },
+    messages: {
+      preferWebp:
+        'Image "{{path}}" is not WebP. Convert it at https://tools.sturge.dev/webp',
+    },
+    schema: [],
+  },
+  create(context) {
+    function check(node, value) {
+      const match = findNonWebpImage(value);
+      if (match) {
+        context.report({
+          node,
+          messageId: "preferWebp",
+          data: { path: match },
+        });
+      }
+    }
+
+    return {
+      Literal(node) {
+        check(node, node.value);
+      },
+      TemplateLiteral(node) {
+        if (node.quasis.length === 1) {
+          check(node, node.quasis[0].value.cooked);
+        }
+      },
+    };
+  },
+};
+
+export default {
+  rules: {
+    "prefer-webp-images": preferWebpImages,
+  },
+};

package/template/eslint.config.js

@@ -8,6 +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 adamjsturge from "./eslint-rules/prefer-webp-images.js";
 
 export default tseslint.config({
   extends: [
@@ -25,6 +26,7 @@ export default tseslint.config({
     "jsx-a11y": jsxA11y,
     "react-hooks": reactHooks,
     "react-refresh": reactRefresh,
+    adamjsturge,
   },
   languageOptions: {
     parserOptions: {
@@ -48,6 +50,7 @@ export default tseslint.config({
       "warn",
       { allowConstantExport: true },
     ],
+    "adamjsturge/prefer-webp-images": "error",
   },
   files: ["**/*.{ts,tsx}"],
   ignores: ["dist"],

package/template/eslint.config.no-webp.js

@@ -0,0 +1,54 @@
+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 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";
+
+export default tseslint.config({
+  extends: [
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    ...tseslint.configs.strict,
+    prettier,
+    promisePlugin.configs["flat/recommended"],
+    importPlugin.flatConfigs.recommended,
+    importPlugin.flatConfigs.typescript,
+    unicorn.configs["unopinionated"],
+    deMorgan.configs.recommended,
+  ],
+  plugins: {
+    "jsx-a11y": jsxA11y,
+    "react-hooks": reactHooks,
+    "react-refresh": reactRefresh,
+  },
+  languageOptions: {
+    parserOptions: {
+      ecmaFeatures: {
+        jsx: true,
+      },
+    },
+  },
+  rules: {
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        argsIgnorePattern: "^_",
+        varsIgnorePattern: "^_",
+        caughtErrorsIgnorePattern: "^_",
+      },
+    ],
+    ...jsxA11y.flatConfigs.strict.rules,
+    ...reactHooks.configs.recommended.rules,
+    "react-refresh/only-export-components": [
+      "warn",
+      { allowConstantExport: true },
+    ],
+  },
+  files: ["**/*.{ts,tsx}"],
+  ignores: ["dist"],
+});

package/template/index.html

@@ -3,6 +3,25 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta
+      name="description"
+      content="__PROJECT_NAME__ — a React app built with create-react-adam"
+    />
+    <meta name="theme-color" content="#2563eb" />
+    <meta property="og:title" content="__PROJECT_NAME__" />
+    <meta
+      property="og:description"
+      content="__PROJECT_NAME__ — a React app built with create-react-adam"
+    />
+    <meta property="og:type" content="website" />
+    <meta name="twitter:card" content="summary" />
+    <link
+      rel="preload"
+      href="/fonts/InterVariable.woff2"
+      as="font"
+      type="font/woff2"
+      crossorigin
+    />
     <title>__PROJECT_NAME__</title>
   </head>
   <body>

package/template/lighthouserc.json

@@ -0,0 +1,17 @@
+{
+  "ci": {
+    "collect": {
+      "startServerCommand": "npm run preview",
+      "startServerReadyPattern": "Local",
+      "url": ["http://localhost:4173/"],
+      "numberOfRuns": 3
+    },
+    "assert": {
+      "assertions": {
+        "categories:accessibility": ["error", { "minScore": 0.95 }],
+        "categories:seo": ["error", { "minScore": 0.95 }],
+        "categories:performance": ["error", { "minScore": 0.85 }]
+      }
+    }
+  }
+}

package/template/npmrc

@@ -0,0 +1,2 @@
+save-exact=true
+

package/template/package.json

@@ -19,32 +19,32 @@
     "test:e2e:report": "cd e2e && allure generate ./allure-results --clean && allure open"
   },
   "dependencies": {
-    "react": "19.2.0",
-    "react-dom": "19.2.0",
-    "react-icons": "5.5.0",
-    "wouter": "3.8.0"
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "react-icons": "5.7.0",
+    "wouter": "3.10.0"
   },
   "devDependencies": {
-    "@eslint/js": "9.39.1",
-    "@tailwindcss/vite": "4.1.17",
-    "@types/react": "19.2.7",
+    "@eslint/js": "9.39.4",
+    "@tailwindcss/vite": "4.3.2",
+    "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "5.1.1",
-    "eslint": "9.39.1",
+    "@vitejs/plugin-react": "5.2.0",
+    "eslint": "9.39.4",
     "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-de-morgan": "2.0.0",
+    "eslint-plugin-de-morgan": "2.1.2",
     "eslint-plugin-import": "2.32.0",
     "eslint-plugin-jsx-a11y": "6.10.2",
-    "eslint-plugin-promise": "7.2.1",
-    "eslint-plugin-react-hooks": "7.0.1",
-    "eslint-plugin-react-refresh": "0.4.24",
+    "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",
-    "prettier": "3.6.2",
+    "prettier": "3.9.5",
     "prettier-plugin-organize-imports": "4.3.0",
-    "prettier-plugin-tailwindcss": "0.7.1",
-    "tailwindcss": "4.1.17",
+    "prettier-plugin-tailwindcss": "0.8.0",
+    "tailwindcss": "4.3.2",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.48.0",
-    "vite": "7.2.4"
+    "typescript-eslint": "8.63.0",
+    "vite": "7.3.6"
   }
 }

package/template/public/robots.txt

@@ -0,0 +1,5 @@
+User-agent: *
+Allow: /
+
+# Add your sitemap URL once deployed:
+# Sitemap: https://example.com/sitemap.xml

package/template/src/App.tsx

@@ -1,17 +1,51 @@
-import { Redirect, Route, Switch } from "wouter";
-import About from "./pages/About";
-import Home from "./pages/Home";
-import NotFound from "./pages/NotFound";
+import { lazy, Suspense, useDeferredValue, useEffect } from "react";
+import { Redirect, Route, Switch, useLocation } from "wouter";
+import { preloadAllRoutesWhenIdle, routeImports } from "./routes";
 
-const App = () => (
-  <Switch>
-    <Route path="/" component={Home} />
-    <Route path="/about" component={About} />
-    <Route path="/home">
-      <Redirect to="/" />
-    </Route>
-    <Route component={NotFound} />
-  </Switch>
-);
+// 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 = () => {
+  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;