Progressive Web Applications (PWAs) provide app-like experiences natively on the web. However, because PWAs run Service Workers that intercept network requests, browsers enforce a strict Secure Origin Policy. Except for http://localhost, service workers, web push notifications, and hardware APIs (like camera, microphone, and geolocation) will not execute over standard HTTP.

While http://localhost works fine for desktop testing, debugging PWAs on real mobile devices over a local Wi-Fi network presents a major roadblock. Accessing your computer's local IP address (e.g., http://192.168.1.100:3000) from a physical phone is blocked by the browser because it is not recognized as a secure origin.

To test and debug PWAs reliably on real mobile devices, you must run your local development server over HTTPS with trusted custom certificates.

This article details how to configure local HTTPS in Next.js using mkcert and the native --experimental-https dev flag, mirroring the exact setup used in the Tetangga App community portal.

🛠️ Step 1: Install mkcert

mkcert is a simple tool for making locally-trusted development certificates. It manages its own local Certificate Authority (CA) and registers it in your system trust store automatically.

Install mkcert on your host operating system:

# macOS (using Homebrew)
brew install mkcert
brew install nss # For Firefox support

# Linux (Ubuntu/Debian)
sudo apt install certutil
sudo apt install mkcert

# Windows (using Chocolatey)
choco install mkcert

Once installed, generate your local Certificate Authority. This is a one-time command:

mkcert -install

🔑 Step 2: Generate Custom SSL Certificates

Now, create a directory in your Next.js project to store the development certificates securely (it is highly recommended to add these to your .gitignore file):

mkdir certificates
cd certificates

Generate the local certificate and private key specifically for localhost and your local IP address:

# Replace 192.168.1.100 with your computer's actual local Wi-Fi IP address
mkcert localhost 127.0.0.1 192.168.1.100 ::1

This will output two files in your certificates/ directory:

1. localhost.pem (The SSL Certificate)
2. localhost-key.pem (The Private Key)

Rename them if needed to match your project conventions:

mv localhost+3.pem localhost.pem
mv localhost+3-key.pem localhost-key.pem

🚀 Step 3: Configure the Next.js Dev Script

Next.js includes native support for running development servers over HTTPS without needing external reverse proxies (like Nginx or Caddy).

Open your package.json file and update your dev script to utilize the --experimental-https flags:

{
  "scripts": {
    "dev": "next dev --experimental-https --experimental-https-key ./certificates/localhost-key.pem --experimental-https-cert ./certificates/localhost.pem"
  }
}

Now, launch your development server:

npm run dev

Your Next.js server is now serving natively on https://localhost:3000 with a completely valid, green lock SSL certificate!

📱 Step 4: Connecting a Physical Mobile Device

To test on your phone, both your computer and your phone must be connected to the same local Wi-Fi network.

1. Find Your Local IP Address

Find the IP address of your development machine:

• macOS/Linux: Run ifconfig or ip a (look for inet under your active Wi-Fi interface, e.g., wlan0 or en0).
• Windows: Run ipconfig in Command Prompt.

Example: 192.168.1.100

2. Install the Local CA on Your Mobile Device

Because your phone does not know about mkcert's local CA, it will still show a "Security Warning" unless you install the CA root certificate:

1. Locate the path of the root CA on your computer:

   mkcert -CAROOT

2. Copy the rootCA.pem file from that path to your mobile device (via AirDrop, email, or USB).
3. On iOS:

• Open rootCA.pem and install the profile in Settings.
• Go to Settings > General > About > Certificate Trust Settings and enable full trust for the Root CA.
1. On Android:
• Go to Settings > Security > Encryption & Credentials > Install a Certificate > CA Certificate and select rootCA.pem.

3. Open the PWA

Navigate to https://192.168.1.100:3000 from your phone's browser.

The origin is now completely trusted, allowing your Serwist/Workbox service workers to register, cache assets offline, and test push notifications natively on your physical phone!

💡 Summary of Benefits

By spending 5 minutes configuring local HTTPS, you gain:

1. Exact Mobile Testing: Test mobile-first layout issues directly on real touchscreen mobile devices.
2. Offline Mode Debugging: Test offline synchronization (like Serwist background sync) by physically toggling airplane mode on your device.
3. No Mismatch Bugs: Unlocks camera, geo-tracking, and web-push notifications locally, guaranteeing that features work identical to production.

Automated Local Trust Store Provisioning with mkcert for WebCrypto & Service Workers

Standardize local HTTPS certificates across macOS, Linux, and mobile test devices so secure-context browser APIs (`crypto.subtle`, `navigator.serviceWorker`, WebRTC) behave identically in development and production.