PWA setup · Docs · PyColors

Starter ProPWA setup

Configure the PWA-ready layerLink to section

Starter Pro uses an explicit PWA setup based on Next.js App Router conventions.

Start with a clean PWA foundation.

Starter Pro includes installable app behavior, standalone mode, professional icons, screenshots, and offline-ready routing without unsafe cache strategies.

PWA overview

One-time payment · Instant access after purchase

Core principle

The PWA layer should be easy to audit, easy to replace, and safe for SaaS products with authentication, billing, and protected app data.

Recommended structureLink to section

layout.tsx

manifest.ts

favicon.ico

icon.png

apple-icon.png

sw.js

icon-192.png

icon-512.png

maskable-icon-512.png

dashboard-desktop.png

dashboard-mobile.png

Setup flowLink to section

Add the PWA configLink to section

lib/pwa/pwa-config.ts

export const pwaConfig = {
  name: 'PyColors Starter Pro',
  shortName: 'Starter Pro',
  description:
    'Production-ready SaaS starter with auth, billing, dashboard and installable PWA foundations.',
  themeColor: '#0b0b10',
  backgroundColor: '#0b0b10',
  brandColor: 'oklch(0.68 0.19 292)',
  display: 'standalone',
  orientation: 'portrait',
} as const;

Add the manifestLink to section

app/manifest.ts

import type { MetadataRoute } from 'next';

import { pwaConfig } from '@/lib/pwa/pwa-config';

export default function manifest(): MetadataRoute.Manifest {
  return {
    id: '/',
    name: pwaConfig.name,
    short_name: pwaConfig.shortName,
    description: pwaConfig.description,
    start_url: '/',
    scope: '/',
    display: 'standalone',
    orientation: 'portrait',
    theme_color: pwaConfig.themeColor,
    background_color: pwaConfig.backgroundColor,
    categories: ['business', 'productivity', 'developer'],
    icons: [
      {
        src: '/pwa/icon-192.png',
        sizes: '192x192',
        type: 'image/png',
      },
      {
        src: '/pwa/icon-512.png',
        sizes: '512x512',
        type: 'image/png',
      },
      {
        src: '/pwa/maskable-icon-512.png',
        sizes: '512x512',
        type: 'image/png',
        purpose: 'maskable',
      },
    ],
    screenshots: [
      {
        src: '/pwa/dashboard-desktop.png',
        sizes: '1280x720',
        type: 'image/png',
        form_factor: 'wide',
        label: 'Starter Pro dashboard workspace',
      },
      {
        src: '/pwa/dashboard-mobile.png',
        sizes: '390x844',
        type: 'image/png',
        form_factor: 'narrow',
        label: 'Starter Pro mobile dashboard',
      },
    ],
  };
}

Register the service workerLink to section

components/pwa/pwa-register.tsx

'use client';

import { useEffect } from 'react';

export function PwaRegister() {
  useEffect(() => {
    if (!('serviceWorker' in navigator)) {
      return;
    }

    const registerServiceWorker = async () => {
      try {
        await navigator.serviceWorker.register('/sw.js');
      } catch {
        // PWA enhancements must never break the core app.
      }
    };

    void registerServiceWorker();
  }, []);

  return null;
}

Add the offline routeLink to section

route.txt

app/offline/page.tsx

Asset requirementsLink to section

PWA icons

`icon-192.png`, `icon-512.png`, and `maskable-icon-512.png` power install surfaces and app launcher presentation.

Apple icon

`apple-icon.png` should be available at the public root for iOS home screen support.

Screenshots

`dashboard-desktop.png` and `dashboard-mobile.png` improve the install preview and product perception.

Setup decisionsLink to section

Recommended

Manual PWA foundation

Starter Pro starts with an explicit manifest, explicit service worker, and clear offline fallback strategy.

easy to audit
simple to customize
safe for auth and billing
no aggressive cache defaults

Later

Advanced PWA library

You can add a more advanced PWA library later if your product needs deeper caching or offline behavior.

runtime cache strategies
precache automation
update prompts
background sync

Prefer / avoidLink to section

Prefer

keep auth and billing online-first
use a lightweight public/sw.js
use real dashboard screenshots
keep NEXT_PUBLIC_APP_URL configurable
test with pnpm build && pnpm start

Avoid

hardcoding production URLs in reusable starter code
caching Stripe or subscription state
using oversized screenshots
testing PWA only in pnpm dev
making service worker failures break the app

Common questionsLink to section

PWA overviewUnderstand the product and business role of PWA-ready foundations inside Starter Pro.PWA production checklistValidate installability, icons, screenshots, service worker, offline fallback, and release readiness.Environment variablesConfigure `NEXT_PUBLIC_APP_URL`, production domains, auth, database, email, and billing variables.ArchitectureReview route groups, layouts, feature modules, server boundaries, and product structure.