create-react-adam 0.5.1 → 0.6.1

package/README.md

@@ -19,6 +19,7 @@ Running without flags opens an interactive wizard where you pick features
 │ ◼ Utility functions (classNames, Storage, useUrlState, safeTimeout)
 │ ◼ Lighthouse CI workflow (a11y/SEO/performance budgets)
 │ ◼ ESLint rule: prefer WebP images
+│ ◼ PWA (installable app + offline support via vite-plugin-pwa)
 └
 ```
 
@@ -42,8 +43,9 @@ Running without flags opens an interactive wizard where you pick features
 - `--with-utils` / `--no-utils` - Include or skip utility functions
 - `--with-lighthouse` / `--no-lighthouse` - Include or skip the Lighthouse CI workflow
 - `--with-webp-lint` / `--no-webp-lint` - Include or skip the prefer-webp-images ESLint rule
+- `--with-pwa` / `--no-pwa` - Include or skip PWA support (installable, works offline)
 
-Any feature answered by a flag is removed from the wizard; if all four are
+Any feature answered by a flag is removed from the wizard; if all five are
 answered, the wizard is skipped entirely.
 
 ## What's Included
@@ -67,7 +69,7 @@ Every generated project starts with:
   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`
+  tags, theme-color, an SVG favicon, plus a `public/robots.txt`
 - **Accessible shell** - skip-to-content link, `<main>` landmark, visible
   `:focus-visible` styles, and per-route document titles
 
@@ -102,6 +104,22 @@ When you include E2E testing (via wizard or `--with-e2e` flag), you get:
 - Pre-configured test setup with example tests
 - HTML reports and Allure integration
 
+### Optional PWA Support
+
+When you include PWA support (via wizard or `--with-pwa` flag), the app
+becomes an installable Progressive Web App:
+
+- **vite-plugin-pwa** configured in `vite.config.ts`, with comments explaining
+  every option
+- Production builds generate a precaching service worker (`dist/sw.js`) and a
+  web app manifest (`dist/manifest.webmanifest`); the registration script is
+  injected into `index.html` automatically
+- The app shell (JS, CSS, HTML, SVG, fonts) works offline after the first
+  visit, and client-side routes fall back to the cached `index.html`
+- `registerType: "autoUpdate"` means new deployments replace the old service
+  worker automatically — no "refresh to update" prompt
+- Dev mode is unchanged: the service worker only exists in production builds
+
 ### Git Integration
 
 After scaffolding (when not already inside a git repository), the CLI:
@@ -202,6 +220,7 @@ Runs basic troubleshooting checks:
 ```
 my-app/
 ├── public/
+│   ├── favicon.svg     # App icon (also used by the PWA manifest)
 │   ├── fonts/          # Self-hosted Inter (variable woff2)
 │   └── robots.txt
 ├── src/

package/bin/index.js

@@ -32,6 +32,11 @@ const FEATURES = [
     id: 'webpLint',
     flag: 'webp-lint',
     label: 'ESLint rule: prefer WebP images'
+  },
+  {
+    id: 'pwa',
+    flag: 'pwa',
+    label: 'PWA (installable app + offline support via vite-plugin-pwa)'
   }
 ];
 
@@ -97,6 +102,8 @@ function printUsage() {
   console.log('  --no-lighthouse       Skip Lighthouse CI workflow');
   console.log('  --with-webp-lint      Include the prefer-webp-images ESLint rule');
   console.log('  --no-webp-lint        Skip the prefer-webp-images ESLint rule');
+  console.log('  --with-pwa            Include PWA support (installable, works offline)');
+  console.log('  --no-pwa              Skip PWA support');
 }
 
 async function resolveFeatures(flags) {
@@ -339,6 +346,22 @@ async function main() {
     }
     await rm(noWebpConfigPath);
 
+    // Resolve the vite config variant: the template's vite.config.ts is the
+    // PWA version (vite-plugin-pwa + web app manifest); vite.config.no-pwa.ts
+    // is the plain version used when the PWA feature is skipped. When PWA is
+    // off, also drop the now-unused vite-plugin-pwa devDependency so it never
+    // gets installed.
+    const noPwaConfigPath = join(projectPath, 'vite.config.no-pwa.ts');
+    if (!features.pwa) {
+      await copyFile(noPwaConfigPath, join(projectPath, 'vite.config.ts'));
+
+      const pkgPath = join(projectPath, 'package.json');
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf-8'));
+      delete pkg.devDependencies['vite-plugin-pwa'];
+      await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf-8');
+    }
+    await rm(noPwaConfigPath);
+
     // README.md uses {{PROJECT_NAME}} because Prettier's markdown formatter
     // rewrites __PROJECT_NAME__ (underscore emphasis) to **PROJECT_NAME**.
     const replacements = {
@@ -350,6 +373,9 @@ async function main() {
       'package.json',
       'index.html',
       'README.md',
+      // vite.config.ts only has placeholders in its PWA variant (the web app
+      // manifest name); replacing is a harmless no-op otherwise.
+      'vite.config.ts',
       join('src', 'pages', 'Home', 'index.tsx'),
       join('src', 'pages', 'About', 'index.tsx'),
       join('src', 'pages', 'NotFound', 'index.tsx')
@@ -395,6 +421,13 @@ async function main() {
     console.log('    Generates and opens Allure report.\n');
   }
 
+  if (features.pwa) {
+    console.log(
+      'PWA support is on: production builds generate a service worker and web' +
+        '\napp manifest (configured in vite.config.ts); dev mode is unaffected.\n'
+    );
+  }
+
   console.log('We suggest that you begin by typing:\n');
   console.log(`  cd ${projectName}`);
   console.log('  npm run dev\n');

package/package.json

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

package/template/README.md

@@ -122,10 +122,33 @@ location makes it smooth.
 - **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.
+  tags — update them as your app takes shape. `public/robots.txt` and an SVG
+  favicon (`public/favicon.svg`) are included.
 - **Accessibility**: a skip-to-content link, `<main>` landmark, and visible
   `:focus-visible` styles are wired into `App.tsx` / `app.css`.
 
+## PWA (if included)
+
+This app is a Progressive Web App: browsers offer an "Install" option, and
+the app keeps working offline after the first visit.
+
+- Everything is configured in `vite.config.ts` via
+  [vite-plugin-pwa](https://vite-pwa-org.netlify.app) — the web app manifest
+  (name, colors, icon) lives there too. Update it alongside the matching
+  values in `index.html` (`theme-color`) and `public/favicon.svg`.
+- `npm run build` generates the service worker (`dist/sw.js`) and manifest
+  (`dist/manifest.webmanifest`) and injects the registration script into
+  `index.html` — no client code to maintain.
+- The service worker precaches the app shell (JS, CSS, HTML, SVG, fonts) and
+  answers client-side routes with the cached `index.html` when offline.
+- Updates are automatic (`registerType: "autoUpdate"`): a new deployment
+  replaces the old service worker on the user's next visit.
+- Dev mode is unaffected — the service worker only exists in production
+  builds. Test it locally with `npm run build && npm run preview`.
+
+To remove PWA support later: delete the `VitePWA(...)` block and its import
+from `vite.config.ts`, then run `npm uninstall vite-plugin-pwa`.
+
 ## ESLint: prefer-webp-images (if included)
 
 A local rule in `eslint-rules/prefer-webp-images.js` errors on references to

package/template/index.html

@@ -15,6 +15,7 @@
     />
     <meta property="og:type" content="website" />
     <meta name="twitter:card" content="summary" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link
       rel="preload"
       href="/fonts/InterVariable.woff2"

package/template/package.json

@@ -45,8 +45,9 @@
     "prettier-plugin-tailwindcss": "0.8.0",
     "tailwindcss": "4.3.2",
     "typescript": "6.0.3",
-    "typescript-eslint": "8.63.0",
-    "vite": "8.1.4"
+    "typescript-eslint": "8.64.0",
+    "vite": "8.1.4",
+    "vite-plugin-pwa": "1.3.0"
   },
   "overrides": {
     "eslint-plugin-jsx-a11y": {

package/template/public/favicon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <rect width="512" height="512" rx="96" fill="#2563eb" />
+  <g fill="none" stroke="#ffffff" stroke-width="20">
+    <ellipse cx="256" cy="256" rx="176" ry="72" />
+    <ellipse cx="256" cy="256" rx="176" ry="72" transform="rotate(60 256 256)" />
+    <ellipse cx="256" cy="256" rx="176" ry="72" transform="rotate(120 256 256)" />
+  </g>
+  <circle cx="256" cy="256" r="28" fill="#ffffff" />
+</svg>

package/template/vite.config.no-pwa.ts

@@ -0,0 +1,7 @@
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});

package/template/vite.config.ts

@@ -1,7 +1,56 @@
 import tailwindcss from "@tailwindcss/vite";
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
+import { VitePWA } from "vite-plugin-pwa";
 
+// PWA support (optional create-react-adam feature). vite-plugin-pwa makes
+// the app installable and offline-capable: `npm run build` generates a
+// service worker (dist/sw.js) that precaches the app shell, emits a web app
+// manifest (dist/manifest.webmanifest), and injects the registration script
+// into index.html. `npm run dev` is unaffected — the service worker only
+// exists in production builds; test it locally with
+// `npm run build && npm run preview`. Docs: https://vite-pwa-org.netlify.app
 export default defineConfig({
-  plugins: [react(), tailwindcss()],
+  plugins: [
+    react(),
+    tailwindcss(),
+    VitePWA({
+      // New deployments take over automatically on the user's next visit —
+      // no "refresh to update" prompt, no stale app shell.
+      registerType: "autoUpdate",
+      workbox: {
+        // Precache all built JS/CSS/HTML plus SVGs and the self-hosted
+        // fonts, so the entire app shell works offline after the first
+        // visit. Add extensions here if you ship other static assets
+        // (e.g. png, webp) that should be available offline.
+        globPatterns: ["**/*.{js,css,html,svg,woff2}"],
+        // SPA fallback: deep links like /about are client-side routes, so
+        // the service worker answers them with the cached index.html when
+        // offline instead of failing with a network error.
+        navigateFallback: "index.html",
+      },
+      // The install metadata browsers read for "Install app" / "Add to
+      // Home Screen": the installed app's name, icon, and window colors.
+      manifest: {
+        name: "__PROJECT_NAME__",
+        short_name: "__PROJECT_NAME__",
+        description: "A React app built with create-react-adam",
+        // Keep in sync with the theme-color <meta> tag in index.html.
+        theme_color: "#2563eb",
+        // Splash-screen background while the app loads; matches
+        // --color-brand-background in src/app.css.
+        background_color: "#f8fafc",
+        display: "standalone",
+        icons: [
+          {
+            // SVG icons scale to any size; swap in 192x192 and 512x512
+            // PNGs here if you need to support older devices.
+            src: "/favicon.svg",
+            sizes: "any",
+            type: "image/svg+xml",
+          },
+        ],
+      },
+    }),
+  ],
 });