Remove adhoc manifest.json page, update Vite PWA config, implement PWA E2E tess

Author: webstackdev

.gitignore

@@ -1,5 +1,6 @@
 # build output
 dist/
+dev-dist/
 
 # generated types
 .astro/

@types/virtual-pwa-register.d.ts

@@ -0,0 +1,11 @@
+declare module 'virtual:pwa-register' {
+  export interface RegisterSWOptions {
+    immediate?: boolean
+    onNeedRefresh?: () => void
+    onOfflineReady?: () => void
+    onRegistered?: (registration: ServiceWorkerRegistration | undefined) => void
+    onRegisterError?: (error: Error) => void
+  }
+
+  export function registerSW(options?: RegisterSWOptions): (reloadPage?: boolean) => Promise<void>
+}

@types/window.d.ts

@@ -2,6 +2,7 @@
  * Global Window interface extensions
  * Centralizes all custom properties added to the window object
  */
+import type { registerSW } from 'virtual:pwa-register'
 import type { EvaluationError } from '@test/errors/EvaluationError'
 
 /**
@@ -89,6 +90,11 @@ declare global {
      */
     __astroPageLoadCounter?: number
     __astroPageLoadListenerAttached?: boolean
+
+    /**
+     * Indicates whether the window is running inside a web worker context
+     */
+    __pwaUpdateSW?: ReturnType<typeof registerSW> | null
   }
 }
 

_TODO.md

@@ -2,7 +2,7 @@
 
 ## See the @TODO: about enabling the PWA to be used as a share target for other apps in src/pages/manifest.json.ts
 
-## Make sure all of the pages/testing files are wrapped in BaseLayout for consistency.
+## Make sure all of the pages/testing files are wrapped in BaseLayout for consistency
 
 ## Analytics
 
@@ -70,7 +70,7 @@ Shared Types vs Swagger / Keeping Docs in Sync
 
 2. Code-first OpenAPI (Zod or TS schemas → OpenAPI)
 
-- Define schemas in Zod/Valibot (or ts-rest) alongside the endpoint. Generate OpenAPI JSON plus TypeScript types from those schemas. Docs (Swagger UI/Redoc) and any client SDKs come from the generated spec, so they’re always in sync.
+- Define schemas in Zod/Valibot (or ts-rest) alongside the endpoint. Generate OpenAPI JSON plus TypeScript types from those schemas. Docs (Swagger UI/Redoc) and any client SDKs come from the generated spec, so they're always in sync.
 - Guarantees: CI regenerates the spec and fails when the checked-in artifact is stale; endpoint handlers reuse the same schema for runtime validation, so a mismatch cannot compile.
 
 3. Spec-first OpenAPI + Swagger Codegen

astro.config.ts

@@ -10,7 +10,7 @@ import { defineConfig } from 'astro/config'
 import { fileURLToPath } from 'node:url'
 import type { PluginOption } from 'vite'
 /**
- * You cannot use path aliases (@lib, @components, etc.) in files that are
+ * You cannot use path aliases (`@lib`, `@components`, etc.) in files that are
  * imported by astro.config.ts, because the path alias resolution happens
  * AFTER the config is loaded, not before. This means that adding resolve.alias
  * paths to the vite section in astro.config.ts would not allow using path
@@ -24,21 +24,22 @@ import {
   isUnitTest,
   isVercel,
   markdownConfig,
-  serviceWorkerConfig,
+  pwaConfig,
   vercelConfig,
 } from './src/lib/config'
 import { callToActionValidator } from './src/integrations/CtaValidator'
 import { faviconGenerator } from './src/integrations/FaviconGenerator'
 import { packageRelease } from './src/integrations/PackageRelease'
 import { privacyPolicyVersion } from './src/integrations/PrivacyPolicyVersion'
+import { pwaDevAssetServer } from './src/lib/plugins/pwaDevAssetServer'
 import { createSerializeFunction, pagesJsonWriter } from './src/integrations/sitemapSerialize'
 
 const sharedTestIntegrations = [
   icon(),
 ]
 
 const standardIntegrations = [
-  AstroPWA(serviceWorkerConfig),
+  AstroPWA(pwaConfig),
   ...sharedTestIntegrations,
   mdx(markdownConfig),
   /** Generate favicons and PWA icons from source SVG */
@@ -104,6 +105,7 @@ export default defineConfig({
     /* @ts-expect-error - tailwindcss plugin type compatibility */
     plugins: [
       tailwindcss(),
+      pwaDevAssetServer(),
     ] as PluginOption[],
     resolve: {
       alias: {

eslint.config.ts

@@ -161,6 +161,7 @@ export default [
         {
           ignore: [
             '^astro:.*',  // Ignore Astro virtual modules
+            '^virtual:pwa-register$',
             '^\\./.*',    // Ignore relative imports (let TypeScript handle these)
           ],
         },
@@ -429,6 +430,7 @@ export default [
 
   {
     files: [
+      'src/lib/config/pwa.ts',
       'src/lib/config/serviceWorker.ts',
       'src/components/scripts/store/__tests__/socialEmbeds.spec.ts',
       'src/pages/api/**/*',

src/components/Errors/NotFoundHero/index.astro

@@ -0,0 +1,33 @@
+---
+export interface Props {
+  heading?: string
+  subheading?: string
+  description?: string
+  ctaHref?: string
+  ctaLabel?: string
+}
+
+const {
+  heading = '404',
+  subheading = 'Page Not Found',
+  description = "Sorry, the page you are looking for doesn't exist or has been moved.",
+  ctaHref = '/',
+  ctaLabel = 'Go Home',
+} = Astro.props
+---
+
+<div class="mb-8 text-center">
+  <h1 class="text-9xl font-bold text-text-muted mb-4">{heading}</h1>
+  <h2 class="text-3xl md:text-4xl font-bold text-text mb-4">{subheading}</h2>
+  <p class="text-lg text-text-muted mb-8">
+    {description}
+  </p>
+  <div class="space-y-4">
+    <a
+      href={ctaHref}
+      class="inline-flex items-center justify-center px-6 py-3 border border-transparent text-base font-medium rounded-lg text-white bg-primary hover:bg-primary-hover focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-primary transition-colors duration-200"
+    >
+      {ctaLabel}
+    </a>
+  </div>
+</div>

src/components/Head/Meta.astro

@@ -85,8 +85,6 @@ const { slug, defaultTheme } = getMetaThemeData(path)
 <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
 {/* Status bar style with values such as "default" or "black-translucent" */}
 <meta name="apple-mobile-web-app-status-bar-style" content="default" />
-{/* Web manifest file for Progressive Web Application app usage */}
-<link rel="manifest" href={absoluteUrl('manifest.json', Astro.site)} />
 {/* Allows the web app to run in full-screen mode */}
 <meta name="mobile-web-app-capable" content="yes">
 {/* RSS Feed */}
@@ -96,6 +94,8 @@ const { slug, defaultTheme } = getMetaThemeData(path)
   href={absoluteUrl('rss.xml', Astro.site)}
   title={`RSS Feed for ${contactData.company.name}`}
 />
+{/* Web App Manifest */}
+<link rel="manifest" href="/manifest.json" />
 {/* Webmentions */}
 <link rel="pingback" href={`https://webmention.io/${Astro.site!.hostname}/xmlrpc`} />
 <link rel="webmention" href={`https://webmention.io/${Astro.site!.hostname}/webmention`} />

src/components/Pwa/RegisterSW.astro

@@ -0,0 +1 @@
+<script type="module" src="/src/components/Pwa/register-sw.ts"></script>

src/components/Pwa/register-sw.ts

@@ -0,0 +1,38 @@
+import { registerSW } from 'virtual:pwa-register'
+
+const registerServiceWorker = () => {
+  const hasServiceWorker = 'serviceWorker' in navigator
+  console.info('[pwa] register-sw start', { hasServiceWorker })
+
+  if (!hasServiceWorker) {
+    return
+  }
+
+  const updateSW = registerSW({
+    immediate: false,
+    onNeedRefresh() {
+      window.dispatchEvent(new CustomEvent('pwa:need-refresh'))
+    },
+    onOfflineReady() {
+      window.dispatchEvent(new CustomEvent('pwa:offline-ready'))
+    },
+    onRegistered(registration) {
+      console.info('[pwa] service worker registered', {
+        scope: registration?.scope,
+        installing: Boolean(registration?.installing),
+        waiting: Boolean(registration?.waiting),
+        active: Boolean(registration?.active),
+      })
+    },
+    onRegisterError(error) {
+      console.error('[pwa] service worker registration error', error)
+    },
+  })
+
+  console.info('[pwa] register-sw hooked update handler')
+
+  window.__pwaUpdateSW = updateSW
+
+}
+
+registerServiceWorker()