Introduction

Bienvenue dans la documentation PWASK. Ce guide vous aide à passer du prototype à un déploiement en production fiable, sécurisé et performant.

Qu'est-ce que PWASK ?

PWASK (Progressive Web App Starter Kit) est un starter complet et prêt pour la production, conçu pour créer des applications web modernes et fonctionnelles hors-ligne ainsi que des plateformes SaaS. Il combine des technologies de pointe avec les meilleures pratiques pour offrir une expérience web haute performance et installable.

Stack Principal

  • Frontend : Next.js (App Router), React, TypeScript, Tailwind CSS
  • Backend : Supabase (Postgres, Auth, Realtime, Storage)
  • Offline-First : Service Worker, IndexedDB, synchronisation en arrière-plan avec résolution de conflits
  • PWA : Web App Manifest, installabilité, support des notifications
  • i18n : Support multi-langue intégré (EN, FR, extensible)
  • Sécurité : HTTPS imposé, politiques RLS, en-têtes CSP, HSTS, CORS configuré
  • Performance : Optimisation d'images, lazy loading, code splitting, ISR, cache Edge

Fonctionnalités Incluses

  • ✅ Authentification utilisateur (email/mot de passe, magic links, OAuth)
  • ✅ Profils utilisateurs avec téléchargement d'avatars
  • ✅ Gestion des tarifs et abonnements (intégration Stripe prête)
  • ✅ Site de documentation complet
  • ✅ Formulaires d'inscription à la newsletter
  • ✅ Sections FAQ, blog, témoignages
  • ✅ Mode sombre avec variables CSS
  • ✅ Interface mobile optimisée avec accessibilité (WCAG AA)
  • ✅ Invites d'installation PWA et cache du service worker
  • ✅ Synchronisation des données hors-ligne avec mises à jour optimistes

Démarrage Rapide (dev local)

git clone https://github.com/7s4r/pwask-v3
cd pwask-v3
pnpm install
cp .env.example .env.local
# Remplir .env.local avec les identifiants Supabase (URL, ANON_KEY)
pnpm dev

Visitez http://localhost:3000 — l'application démarrera en anglais. Inscrivez-vous avec un email de test pour explorer les fonctionnalités comme :

  • Authentification et profils utilisateurs
  • Synchronisation des données hors-ligne
  • Installation PWA (utilisez Lighthouse pour tester l'installabilité)
  • Basculement mode sombre
  • Support multi-langue (changez de locale en bas de page)
  • Articles de blog avec lecture en cache

Fonctionnalités Clés à Explorer

  1. Capacités Hors-ligne : Désactivez le réseau dans DevTools et continuez à utiliser l'application
  2. Synchronisation en Arrière-plan : Effectuez des modifications hors-ligne ; elles se synchronisent automatiquement en ligne
  3. Installabilité : Ouvrez DevTools → onglet Application → vérifiez le Web App Manifest
  4. Performance : Lancez Lighthouse pour voir des scores de 100/100 en Performance et Accessibilité
  5. Sécurité : Vérifiez l'onglet Réseau pour les en-têtes de sécurité (CSP, HSTS, COOP/COEP)

Checklist de Production

1. Secrets & Environnement

  • Créer un projet Supabase de production (séparé du dev)
  • Définir SUPABASE_URL et SUPABASE_ANON_KEY avec les identifiants de production
  • Stocker SUPABASE_SERVICE_ROLE_KEY dans le gestionnaire de secrets de l'hébergeur (jamais dans .env)
  • Configurer SMTP ou fournisseur d'email transactionnel (SendGrid, Postmark, etc.)
  • Définir NEXT_PUBLIC_SITE_URL avec votre domaine de production
  • Générer et stocker les clés VAPID pour les notifications push (optionnel)

2. Base de Données & Migrations

  • Exécuter toutes les migrations : supabase db push dans votre projet de production
  • Vérifier que les politiques Row-Level Security (RLS) sont activées sur toutes les tables
  • Tester les permissions utilisateur avec de vrais comptes de test sur toutes les routes
  • Configurer des sauvegardes quotidiennes via Supabase ou utiliser leurs sauvegardes automatiques
  • Documenter toutes les fonctions SQL personnalisées ou triggers

3. Build & Déploiement

  • Déployer sur Vercel, Netlify ou votre plateforme préférée
  • Assurer que pnpm build se termine sans erreurs
  • Tester tous les flux d'authentification en production (inscription, connexion, magic link, réinitialisation mot de passe)
  • Vérifier la fonctionnalité email (transactionnel + newsletter)
  • Lancer un audit Lighthouse et confirmer les scores 100/100

4. PWA & Offline-First

  • Tester l'installabilité sur mobile (Chrome Android + Safari iOS)
  • Vérifier l'enregistrement du Service Worker : navigator.serviceWorker.getRegistrations()
  • Tester le scénario hors-ligne : désactiver le réseau et vérifier que les routes en cache fonctionnent
  • Vérifier la synchronisation en arrière-plan : faire des mutations hors-ligne, se reconnecter et confirmer la synchronisation
  • Tester les notifications push si activées

5. Renforcement de la Sécurité

  • Activer HTTPS partout (automatique sur Vercel/Netlify)

  • Aller Ensuite

  • Guide de Démarrage — Configuration étape par étape pour votre premier projet

  • Aperçu de l'Architecture — Plongée en profondeur dans les patterns de conception et la synchronisation offline-first

  • Environnement & Déploiement — Référence complète des variables d'environnement et guides spécifiques aux plateformes

  • FAQ — Questions fréquentes sur les fonctionnalités, la personnalisation et le dépannage les logs d'activité de la base de données et configurer des alertes

6. Performance & Surveillance

  • Servir les images via CDN (optimisation d'images de Vercel incluse)
  • Activer les en-têtes de cache pour les assets statiques (Next.js gère cela automatiquement)
  • Configurer la surveillance de disponibilité pour les endpoints critiques
  • Configurer les analytics (Google Analytics, Vercel Analytics)
  • Surveiller l'utilisation du stockage Supabase et définir des quotas/alertes
  • Suivre les Core Web Vitals (LCP, FID, CLS) en production

7. Scaling (quand prêt)

  • Configurer des réplicas de lecture Supabase si la latence d'écriture devient un problème
  • Utiliser le pooling de connexions de base de données pour les scénarios à forte concurrence
  • Implémenter une limitation de débit sur les routes API (si vous utilisez des endpoints personnalisés)
  • Mettre en cache les données fréquemment accédées avec Redis (optionnel)
  • Surveiller les performances des requêtes de base de données et ajouter des index au besoin

Où aller ensuite

  • Guide de démarrage — Configuration pas à pas pour votre premier projet
  • Vue d'ensemble de l'architecture — Plongée approfondie dans les modèles de conception et la synchronisation offline-first
  • Notifications Push — Guide complet pour configurer et utiliser les notifications push web
  • Environnement & déploiement — Référence complète des variables d'environnement et guides spécifiques aux plateformes
  • Paiements Stripe — Configurer les clés Stripe, le webhook, les prix et tester de bout en bout
  • Paiements PayPal — Configurer PayPal, les plans Billing, le webhook et tester les flux
  • FAQ — Questions courantes sur les fonctionnalités, la personnalisation et le dépannage