create-react-adam 0.2.2 → 0.3.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,159 @@ 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).
 
-Runs ESLint to check for code quality issues.
+### `npm run setFormatToPrecommitHook`
 
-### `npm run format`
+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.
 
-Formats all files with Prettier, organizing imports and sorting Tailwind classes.
+### `npm run test:e2e` (if E2E was included)
 
-## Tech Stack
+Runs Playwright E2E tests from the `e2e/` directory. `test:e2e:ui` opens
+Playwright UI mode and `test:e2e:report` generates an Allure report.
 
-- **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
+### `npm run itDoesNotWork`
+
+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
+├── types/          # Shared TypeScript types
+├── utils/          # Utility functions (if included)
+├── App.tsx         # Routing, skip link, <main> landmark
+├── 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 a lazy import and route in `src/App.tsx`
 
 ```tsx
-import NewPage from "./pages/NewPage";
+const NewPage = lazy(() => import("./pages/NewPage"));
 
 // In the Switch component:
 <Route path="/new" component={NewPage} />;
 ```
 
+## 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 adam/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 adam 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,
+    adam,
   },
   languageOptions: {
     parserOptions: {
@@ -48,6 +50,7 @@ export default tseslint.config({
       "warn",
       { allowConstantExport: true },
     ],
+    "adam/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,31 @@
+import { lazy, Suspense } from "react";
 import { Redirect, Route, Switch } from "wouter";
-import About from "./pages/About";
-import Home from "./pages/Home";
-import NotFound from "./pages/NotFound";
+
+const Home = lazy(() => import("./pages/Home"));
+const About = lazy(() => import("./pages/About"));
+const NotFound = lazy(() => import("./pages/NotFound"));
 
 const App = () => (
-  <Switch>
-    <Route path="/" component={Home} />
-    <Route path="/about" component={About} />
-    <Route path="/home">
-      <Redirect to="/" />
-    </Route>
-    <Route component={NotFound} />
-  </Switch>
+  <>
+    <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>
+  </>
 );
 
 export default App;

package/template/src/app.css

@@ -1,19 +1,30 @@
 @import "tailwindcss";
 
+@font-face {
+  font-family: "Inter";
+  font-style: normal;
+  font-weight: 100 900;
+  font-display: swap;
+  src: url("/fonts/InterVariable.woff2") format("woff2");
+}
+
 @theme {
-  --font-sans: "Inter", sans-serif;
+  --font-sans:
+    "Inter", system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
 
-  --color-brand-primary: #3b82f6;
-  --color-brand-primaryHover: #2563eb;
-  --color-brand-primaryActive: #1d4ed8;
+  /* Brand colors are chosen to meet WCAG AA contrast (>= 4.5:1) with white
+     text; keep that in mind when changing them. */
+  --color-brand-primary: #2563eb;
+  --color-brand-primaryHover: #1d4ed8;
+  --color-brand-primaryActive: #1e40af;
 
-  --color-brand-secondary: #8b5cf6;
-  --color-brand-secondaryHover: #7c3aed;
-  --color-brand-secondaryActive: #6d28d9;
+  --color-brand-secondary: #7c3aed;
+  --color-brand-secondaryHover: #6d28d9;
+  --color-brand-secondaryActive: #5b21b6;
 
-  --color-brand-success: #22c55e;
+  --color-brand-success: #15803d;
   --color-brand-warning: #f59e0b;
-  --color-brand-danger: #ef4444;
+  --color-brand-danger: #dc2626;
 
   --color-brand-black: #0f172a;
   --color-brand-white: #ffffff;
@@ -27,3 +38,10 @@
 
   --color-brand-disabled: #94a3b8;
 }
+
+@layer base {
+  :focus-visible {
+    outline: 2px solid var(--color-brand-primary);
+    outline-offset: 2px;
+  }
+}

package/template/src/components/Button.tsx

@@ -0,0 +1,27 @@
+import { ComponentPropsWithoutRef } from "react";
+import { ButtonVariant } from "../types/ui";
+
+interface ButtonProps extends ComponentPropsWithoutRef<"button"> {
+  variant?: ButtonVariant;
+}
+
+const variantClasses: Record<ButtonVariant, string> = {
+  primary: "bg-brand-primary hover:bg-brand-primaryHover",
+  success: "bg-brand-success hover:bg-brand-success/90",
+  danger: "bg-brand-danger hover:bg-brand-danger/90",
+};
+
+const Button = ({ variant = "primary", className, ...props }: ButtonProps) => (
+  <button
+    className={[
+      "text-brand-white rounded-lg px-4 py-2 transition-colors",
+      variantClasses[variant],
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ")}
+    {...props}
+  />
+);
+
+export default Button;