Getting Started with PWASK

This guide walks you through setting up PWASK locally, exploring its features, and deploying to production.

Prerequisites

Before starting, ensure you have:

Node.js 18+ (check with node --version)
pnpm 8+ (install with npm install -g pnpm)
Git (for cloning the repo)
A Supabase account (free at supabase.com)
A code editor (VS Code recommended)

Step 1: Clone & Install

# Clone the repository
git clone <repo>
cd pwask

# Install dependencies
pnpm install

# Verify Node & pnpm versions
node --version  # Should be 18+
pnpm --version  # Should be 8+

Step 2: Set Up Supabase (Local Dev)

Option A: Use Supabase Cloud (Easiest)

Go to supabase.com and sign up (free tier available)
Create a new project:
- Project name: pwask-dev
- Region: Closest to you
- Database password: Generate strong password
Copy your credentials:
- Go to Settings → API
- Copy Project URL and anon key
Create .env.local:

SUPABASE_URL=https://xxxxx.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Option B: Use Local Supabase (Advanced)

If you want to run Supabase locally:

# Install Supabase CLI
npm install -g supabase

# Start local Supabase
supabase start

# You'll see output with local URL & keys
# Copy them to .env.local

Note: Local Supabase requires Docker. See Supabase CLI docs for details.

Step 3: Run Migrations

Apply database schema:

# This runs the SQL migrations in supabase/migrations/
supabase db push

This creates tables like:

auth.users (managed by Supabase Auth)
public.profiles (user data)
public.blog_articles (blog content)

Step 4: Configure Email (Optional)

For payment confirmations and account emails, set up email sending:

Quick Setup for Development:

# Generate Ethereal.email test credentials
node scripts/generate-ethereal-credentials.mjs

Copy the output to your .env.local. With Ethereal, no real emails are sent - perfect for testing!

View sent emails: Visit https://ethereal.email/messages with the credentials.

For production setup and alternative providers (Resend, SendGrid, etc.), see the Email Configuration guide.

Step 5: Start Development Server

pnpm dev

Visit http://localhost:3000 in your browser.

Expected output:

  ▲ Next.js (with Tailwind CSS)
  ◇ Ready in 2.5s
  ◇ Local: http://localhost:3000

Step 6: Explore the App

Sign Up

Click "Get Started" button
Enter email and password
You'll be redirected to the dashboard
Click profile icon → "Profile" to add an avatar

Try Offline Mode

Open DevTools (F12 → Network tab)
Check "Offline" checkbox
Try making changes (e.g., update profile)
Changes should queue locally and sync when online
Uncheck "Offline" and watch sync happen automatically

Check PWA Features

Go to DevTools → Application tab
Click "Manifest" — see Web App Manifest
Click "Service Workers" — see registered service worker
Try installing: address bar → "Install app" (Chrome/Edge)

View Blog

Navigate to Blog section
Try changing language (bottom of page: EN/FR)
Articles are cached; try offline access

Step 7: Customize for Your Product

Update Site Info

Edit src/app/[locale]/layout.tsx:

const metadata: Metadata = {
  title: 'My SaaS App', // Change this
  description: 'My awesome product',
  // ...
};

Add Your Logo

Replace public/images/logo.png with your logo

Update src/components/Header.tsx:

<Image src="/images/logo.png" width={40} height={40} alt="Logo" />

Customize Colors

Edit src/app/[locale]/globals.css:

:root {
  --primary: #3b82f6; /* Your brand color */
  --primary-dark: #1e40af;
  /* ... more colors */
}

Tailwind uses these CSS variables automatically.

Add Custom Pages

Create src/app/[locale]/custom/page.tsx:

'use client'

export default function CustomPage() {
  return (
    <div className="container mx-auto py-12">
      <h1 className="text-4xl font-bold">My Custom Page</h1>
      {/* Your content here */}
    </div>
  )
}

The [locale] folder automatically adds EN/FR routing.

Step 8: Deploy to Production

Choose a Platform

Vercel (Recommended):

Best Next.js support
Free tier available
Automatic deployments from GitHub

Netlify:

Alternative to Vercel
Good GitHub integration
Free tier available

Self-hosted:

Docker container
Full control
Higher operational complexity

Deploy to Vercel

Push code to GitHub
Go to vercel.com
Click "New Project"
Select your GitHub repo
Add environment variables (from Step 2)
Click "Deploy"

Vercel will:

Build your app automatically
Generate a preview URL (shared with PRs)
Deploy main branch to production

Create Production Supabase Project

In Supabase, create a new project called pwask-prod
Copy Project URL and anon key
Update Vercel environment variables:
- Go to Settings → Environment Variables
- Add SUPABASE_URL, SUPABASE_ANON_KEY
- Set to Production environment only
Redeploy

Run Migrations on Production

# Connect to production Supabase
supabase link --project-ref xxxxx  # your prod project ID

# Push migrations to production
supabase db push

Step 9: Set Up Production Email (Recommended)

For production email delivery, we recommend Resend (100 emails/day free).

Quick Setup:

Sign up at resend.com (no credit card required)
Verify your domain (or use resend.dev for testing)
Create API key

Add to Vercel environment variables:

EMAIL_HOST=smtp.resend.com
EMAIL_PORT=587
EMAIL_USER=resend
EMAIL_PASS=re_your_api_key_here
EMAIL_FROM=noreply@yourdomain.com

Redeploy your app

Full setup guide: See Email Configuration for:

Complete Resend setup with domain verification
Alternative services (SendGrid, Mailgun, Brevo, Amazon SES)
Deliverability best practices
Troubleshooting

Test Email:

Troubleshooting

"SUPABASE_URL is not defined"

Fix: Ensure .env.local exists and has correct values:

cat .env.local  # should show your Supabase URL

"Cannot find module"

Fix: Reinstall dependencies:

rm -rf node_modules pnpm-lock.yaml
pnpm install

"Service Worker not registering"

Fix: Must use HTTPS in production. Localhost is allowed for dev.

Offline changes not syncing

Fix: Check browser console for errors. Ensure you're reconnecting to internet properly:

// In DevTools console:
navigator.onLine; // should be true when online

Database migration fails

Fix: Check Supabase dashboard for error logs:

Go to Supabase → Settings → Logs
Look for SQL errors
Fix and retry: supabase db push

What's Next?

Architecture Overview — Understand offline-first patterns
Email Configuration — Set up Resend for production and Ethereal for testing
Environment Variables — Configure advanced features
FAQ — Common questions about customization & scaling
Blog — Read performance & security best practices

Support & Resources

GitHub Issues: github.com/pwask/pwask/issues
Supabase Docs: supabase.com/docs
Next.js Docs: nextjs.org/docs
Tailwind Docs: tailwindcss.com/docs

Good luck building with PWASK! 🚀