Introduction

Welcome to the PWASK documentation. This guide helps you move from prototype to a reliable, secure, and performant production deployment.

What is PWASK?

PWASK (Progressive Web App Starter Kit) is a batteries-included, production-ready starter for building modern, offline-capable web applications and SaaS platforms. It combines cutting-edge technologies with best practices to deliver a high-performance, installable web experience.

Core Stack

  • Frontend: Next.js (App Router), React, TypeScript, Tailwind CSS
  • Backend: Supabase (Postgres, Auth, Realtime, Storage)
  • Offline-First: Service Worker, IndexedDB, background sync with conflict resolution
  • PWA: Web App Manifest, installability, notifications support
  • i18n: Built-in multi-language support (EN, FR, extensible)
  • Security: HTTPS enforced, RLS policies, CSP headers, HSTS, CORS configured
  • Performance: Image optimization, lazy loading, code splitting, ISR, Edge caching

What's Included

  • ✅ User authentication (email/password, magic links, OAuth)
  • ✅ User profiles with avatar uploads
  • ✅ Pricing & subscription management (with Stripe integration ready)
  • ✅ Comprehensive documentation site
  • ✅ Newsletter signup forms
  • ✅ FAQ, blog, testimonials sections
  • ✅ Dark mode with CSS variables
  • ✅ Mobile-optimized UI with accessibility (WCAG AA)
  • ✅ PWA installation prompts & service worker caching
  • ✅ Offline data sync with optimistic updates

Quickstart (local dev)

git clone <repo>
cd pwask
pnpm install
cp .env.example .env.local
# Fill .env.local with Supabase credentials (URL, ANON_KEY)
pnpm dev

Visit http://localhost:3000 — the app will start in English. Sign up with a test email to explore features like:

  • User authentication & profiles
  • Offline-first data sync
  • PWA installation (use Lighthouse to test installability)
  • Dark mode toggle
  • Multi-language support (switch locale at the bottom)
  • Blog articles with cached reading

Key Features to Explore

  1. Offline Capabilities: Disable network in DevTools and continue using the app
  2. Background Sync: Make changes offline; they sync automatically when online
  3. Installability: Open DevTools → Application tab → check Web App Manifest
  4. Performance: Run Lighthouse to see 100/100 Performance & Accessibility scores
  5. Security: Check Network tab for security headers (CSP, HSTS, COOP/COEP)

Production Checklist

1. Secrets & Environment

  • Create a Supabase production project (separate from dev)
  • Set SUPABASE_URL and SUPABASE_ANON_KEY to production credentials
  • Store SUPABASE_SERVICE_ROLE_KEY in hosting provider's secret manager (never in .env)
  • Configure SMTP or transactional email provider (SendGrid, Postmark, etc.)
  • Set NEXT_PUBLIC_SITE_URL to your production domain
  • Generate and store VAPID keys for push notifications (optional)

2. Database & Migrations

  • Run all migrations: supabase db push in your production project
  • Verify Row-Level Security (RLS) policies are enabled on all tables
  • Test user permissions with real test accounts across all routes
  • Set up daily backups via Supabase or use their automated backups
  • Document any custom SQL functions or triggers

3. Build & Deployment

  • Deploy to Vercel, Netlify, or your preferred platform
  • Ensure pnpm build completes without errors
  • Test all auth flows in production (sign up, login, magic link, password reset)
  • Verify email functionality (transactional + newsletter)
  • Run Lighthouse audit and confirm 100/100 scores

4. PWA & Offline-First

  • Test installability on mobile (Android Chrome + iOS Safari)
  • Verify Service Worker registration: navigator.serviceWorker.getRegistrations()
  • Test offline scenario: disable network and verify cached routes work
  • Verify background sync: make offline mutations, reconnect, and confirm sync
  • Test push notifications if enabled

5. Security Hardening

  • Enable HTTPS everywhere (automatically on Vercel/Netlify)
  • Review CSP header and whitelist third-party services (analytics, payment providers)
  • Verify HSTS header is present and persistent cache is set
  • Rotate service keys quarterly and revoke old keys immediately
  • Add Sentry or similar error tracking for production issues
  • Enable database activity logs and set up alerts

6. Performance & Monitoring

  • Serve images via CDN (Vercel's image optimization included)
  • Enable caching headers for static assets (Next.js handles this automatically)
  • Set up uptime monitoring for critical endpoints
  • Configure analytics (Google Analytics, Vercel Analytics)
  • Monitor Supabase storage usage and set quotas/alerts
  • Track Core Web Vitals (LCP, FID, CLS) in production

7. Scaling (when ready)

  • Set up Supabase read replicas if write latency becomes an issue
  • Use database connection pooling for high-concurrency scenarios
  • Implement rate limiting on API routes (if using custom endpoints)
  • Cache frequently accessed data with Redis (optional)
  • Monitor database query performance and add indexes as needed

Where to Go Next