| # PWA on Localhost - Important Information | |
| ## Summary | |
| **The PWA files were created successfully**, but they **won't work fully on `localhost:8501`** due to Streamlit's static file serving limitations. | |
| --- | |
| ## What You're Seeing (or Not Seeing) | |
| ### ✅ What DOES Work on Localhost: | |
| 1. **Game functionality**: Everything works normally | |
| 2. **Challenge Mode**: Loading `?game_id=...` works (if HF credentials configured) | |
| 3. **PWA meta tags**: Injected into HTML (check page source) | |
| 4. **Service worker registration attempt**: Runs in browser console | |
| ### ❌ What DOESN'T Work on Localhost: | |
| 1. **`manifest.json` not accessible**: | |
| ``` | |
| http://localhost:8501/app/static/manifest.json | |
| → Returns HTML instead of JSON (Streamlit doesn't serve /app/static/) | |
| ``` | |
| 2. **Icons not accessible**: | |
| ``` | |
| http://localhost:8501/app/static/icon-192.png | |
| → Returns 404 or HTML | |
| ``` | |
| 3. **Service worker fails to register**: | |
| ```javascript | |
| // Browser console shows: | |
| Failed to register service worker: 404 Not Found | |
| ``` | |
| 4. **No PWA install prompt**: | |
| - No banner at bottom of screen | |
| - No install icon in address bar | |
| - PWA features disabled | |
| --- | |
| ## Why This Happens | |
| **Streamlit's Static File Serving:** | |
| - Streamlit only serves files from: | |
| - `/.streamlit/static/` (internal Streamlit assets) | |
| - Component assets via `declare_component()` | |
| - NOT from arbitrary `battlewords/static/` directories | |
| - On HuggingFace Spaces: | |
| - `/app/static/` is mapped by HF infrastructure | |
| - Files in `battlewords/static/` are accessible at `/app/static/` | |
| - ✅ PWA works perfectly | |
| - On localhost: | |
| - No `/app/static/` mapping exists | |
| - Streamlit returns HTML for all unrecognized paths | |
| - ❌ PWA files return 404 | |
| --- | |
| ## How to Test PWA Locally | |
| ### Option 1: Use ngrok (HTTPS Tunnel) ⭐ **RECOMMENDED** | |
| This is the **best way** to test PWA locally with full functionality: | |
| ```bash | |
| # Terminal 1: Run Streamlit | |
| streamlit run app.py | |
| # Terminal 2: Expose with HTTPS | |
| ngrok http 8501 | |
| # Output shows: | |
| # Forwarding https://abc123.ngrok-free.app -> http://localhost:8501 | |
| ``` | |
| **Then visit the HTTPS URL on your phone or desktop:** | |
| - ✅ Full PWA functionality | |
| - ✅ Install prompt appears | |
| - ✅ manifest.json loads | |
| - ✅ Service worker registers | |
| - ✅ Icons display correctly | |
| **ngrok Setup:** | |
| 1. Download: https://ngrok.com/download | |
| 2. Sign up for free account | |
| 3. Install: `unzip /path/to/ngrok.zip` (or chocolatey on Windows: `choco install ngrok`) | |
| 4. Authenticate: `ngrok config add-authtoken <your-token>` | |
| 5. Run: `ngrok http 8501` | |
| --- | |
| ### Option 2: Deploy to HuggingFace Spaces ⭐ **PRODUCTION** | |
| PWA works out-of-the-box on HF Spaces: | |
| ```bash | |
| git add wrdler/static/ wrdler/ui.py | |
| git commit -m "Add PWA support" | |
| git push | |
| # HF Spaces auto-deploys | |
| # Visit: https://[YourUsername]-wrdler.hf.space | |
| ``` | |
| **Then test PWA:** | |
| - Android Chrome: "Add to Home Screen" prompt appears | |
| - iOS Safari: Share → "Add to Home Screen" | |
| - Desktop Chrome: Install icon in address bar | |
| ✅ **This is where PWA is meant to work!** | |
| --- | |
| ###Option 3: Manual Static File Server (Advanced) | |
| You can serve the static files separately: | |
| ```bash | |
| # Terminal 1: Run Streamlit | |
| streamlit run app.py | |
| # Terminal 2: Serve static files | |
| cd wrdler/static | |
| python3 -m http.server 8502 | |
| # Then access: | |
| # Streamlit: http://localhost:8501 | |
| # Static files: http://localhost:8502/manifest.json | |
| ``` | |
| **Then modify the PWA paths in `ui.py`:** | |
| ```python | |
| pwa_meta_tags = """ | |
| <link rel="manifest" href="http://localhost:8502/manifest.json"> | |
| <link rel="apple-touch-icon" href="http://localhost:8502/icon-192.png"> | |
| <!-- etc --> | |
| """ | |
| ``` | |
| ❌ **Not recommended**: Too complex, defeats the purpose | |
| --- | |
| ## What About Challenge Mode? | |
| **Question:** "I loaded `localhost:8501/?game_id=hDjsB_dl` but don't see anything" | |
| **Answer:** Challenge Mode is **separate from PWA**. You should see a blue banner at the top if: | |
| ### ✅ Requirements for Challenge Mode to Work: | |
| 1. **Environment variables configured** (`.env` file): | |
| ```bash | |
| HF_API_TOKEN=hf_xxxxxxxxxxxxx | |
| HF_REPO_ID=Surn/Storage | |
| SPACE_NAME=Surn/BattleWords | |
| ``` | |
| 2. **Valid game_id exists** in the HF repo: | |
| - `hDjsB_dl` must be a real challenge created previously | |
| - Check HuggingFace dataset repo: https://huggingface.co/datasets/Surn/Storage | |
| - Look for: `games/<uid>/settings.json` | |
| - Verify `shortener.json` has entry for `hDjsB_dl` | |
| 3. **Internet connection** (to fetch challenge data) | |
| ### If Challenge Mode ISN'T Working: | |
| **Check browser console (F12 → Console):** | |
| ```javascript | |
| // Look for errors: | |
| "[game_storage] Could not resolve sid: hDjsB_dl" ← Challenge not found | |
| "Failed to load game from sid" ← HF API error | |
| "HF_API_TOKEN not configured" ← Missing credentials | |
| ``` | |
| **If you see errors:** | |
| 1. Verify `.env` file exists with correct variables | |
| 2. Restart Streamlit (`Ctrl+C` and `streamlit run app.py` again) | |
| 3. Try a different `game_id` from a known challenge | |
| 4. Check HF repo has the challenge data | |
| **Note:** Challenge Mode works the same in Wrdler as it did in BattleWords. | |
| --- | |
| ## Summary Table | |
| | Feature | Localhost | Localhost + ngrok | HF Spaces (Production) | | |
| |---------|-----------|-------------------|------------------------| | |
| | **Game works** | ✅ | ✅ | ✅ | | |
| | **Challenge Mode** | ✅ (if .env configured) | ✅ | ✅ | | |
| | **PWA manifest loads** | ❌ | ✅ | ✅ | | |
| | **Service worker registers** | ❌ | ✅ | ✅ | | |
| | **Install prompt** | ❌ | ✅ | ✅ | | |
| | **Icons display** | ❌ | ✅ | ✅ | | |
| | **Full-screen mode** | ❌ | ✅ | ✅ | | |
| --- | |
| ## What You Should Do | |
| ### For Development: | |
| ✅ **Just develop normally on localhost** | |
| - Game features work fine | |
| - Challenge Mode works (if .env configured) | |
| - PWA features won't work, but that's okay | |
| - Test PWA when you deploy | |
| ### For PWA Testing: | |
| ✅ **Use ngrok for quick local PWA testing** | |
| - 5 minutes to setup | |
| - Full PWA functionality | |
| - Test on real phone | |
| ### For Production: | |
| ✅ **Deploy to HuggingFace Spaces** | |
| - PWA works automatically | |
| - No configuration needed | |
| - `/app/static/` path works out-of-the-box | |
| --- | |
| ## Bottom Line | |
| **Your question:** "Should I see something at the bottom of the screen?" | |
| **Answer:** | |
| 1. **PWA install prompt**: ❌ Not on `localhost:8501` (Streamlit limitation) | |
| - **Will work** on HF Spaces production deployment ✅ | |
| - **Will work** with ngrok HTTPS tunnel ✅ | |
| 2. **Challenge Mode banner**: ✅ Should appear at TOP (not bottom) | |
| - Check if `?game_id=hDjsB_dl` exists in your HF repo | |
| - Check browser console for errors | |
| - Verify `.env` has `HF_API_TOKEN` configured | |
| The PWA implementation is **correct** and **ready for production**. It just won't work on bare localhost due to Streamlit's static file serving limitations. Once you deploy to HuggingFace Spaces, everything will work perfectly! | |
| --- | |
| ## Quick Test Command | |
| ```bash | |
| # Check if .env is configured: | |
| cat .env | grep HF_ | |
| # Should show: | |
| # HF_API_TOKEN=hf_xxxxx | |
| # HF_REPO_ID=YourUsername/Storage | |
| # SPACE_NAME=YourUsername/Wrdler | |
| # If missing, Challenge Mode won't work locally | |
| ``` | |
| --- | |
| **Next Steps:** | |
| 1. Test game functionality on localhost ✅ | |
| 2. Deploy to HF Spaces for PWA testing ✅ | |
| 3. Or install ngrok for local PWA testing ✅ | |