Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/pkeffect/pwa-framework

a zero-dependency Python script that scaffolds complete, production-ready Progressive Web App frameworks optimized for game development. Generate 24 files across 11 directories in ~150ms with enterprise-grade features built in.
https://github.com/pkeffect/pwa-framework

css html js python webgl

Last synced: 5 months ago
JSON representation

a zero-dependency Python script that scaffolds complete, production-ready Progressive Web App frameworks optimized for game development. Generate 24 files across 11 directories in ~150ms with enterprise-grade features built in.

Awesome Lists containing this project

README 

          
# PWA Game Framework Generator






![Version](https://img.shields.io/badge/version-2.0.1-blue.svg)

![Python](https://img.shields.io/badge/python-3.10--3.12-green.svg)

![License](https://img.shields.io/badge/license-MIT-orange.svg)

![Build Time](https://img.shields.io/badge/build_time-~150ms-brightgreen.svg)

![Dependencies](https://img.shields.io/badge/dependencies-zero-success.svg)

![Tests](https://github.com/pkeffect/pwa-framework/actions/workflows/validate.yml/badge.svg)



**Generate production-ready PWA game frameworks in milliseconds.**



[Features](#-features) • [Quick Start](#-quick-start) • [Installation](#-installation) • [Documentation](#-documentation) • [Examples](#-examples)






---



## 🎯 Overview



**PWA Game Framework Generator** is a zero-dependency Python script that scaffolds complete, production-ready Progressive Web App frameworks optimized for game development. Generate 24 files across 11 directories in ~150ms with enterprise-grade features built in.



### What You Get



- ✨ **Zero Build Step** - Deploy instantly, no compilation required

- 🚀 **~150ms Generation** - Complete framework in milliseconds

- 📦 **50KB Footprint** - Entire output smaller than most libraries

- ♿ **WCAG 2.1 AA** - Accessibility built-in from day one

- 🔐 **Security Hardened** - CSP, SRI, input validation, error recovery

- 🎨 **High DPI Ready** - Retina display support out of the box

- 📱 **PWA Native** - Installable, offline-capable, app-like

- 🎮 **Game-Focused** - Optimized for game jams, prototypes, education



---



## ✨ Features



### Framework Output



| Feature | Description |

|---------|-------------|

| **ES6 Modules** | Native browser modules, no bundler required |

| **Service Worker** | Offline-first with cache versioning |

| **Asset Pipeline** | Chunked loading with retry logic (2 retries, exponential backoff) |

| **High DPI Canvas** | Auto-scaling for 4K/Retina displays |

| **Scene System** | State machine for menu/game/pause screens |

| **Error Handling** | 3-layer protection (sync/async/resource) |

| **Audio Manager** | Context unlocking for mobile browsers |

| **Accessibility** | Keyboard nav, ARIA labels, focus trapping |

| **Security** | CSP headers (no 'unsafe-inline'), SRI hashes, input sanitization |

| **Dark Mode** | Auto-adapts to system preference (light/dark) |

| **Cache Management** | 50MB size limit with automatic cleanup |

| **Asset Validation** | Image dimension checks (1x1 min, 8192x8192 max) |

| **Browser Compat** | Vendor prefixes for Safari 11+ support |

| **Battery Optimization** | Visibility API integration |



### Generator Features



| Feature | Description |

|---------|-------------|

| **Input Validation** | Sanitization-first approach (fixes vs rejects) |

| **Error Recovery** | Comprehensive exception handling |

| **CLI Interface** | Interactive & non-interactive modes, dry-run support |

| **Zero Dependencies** | Pure Python stdlib (argparse, pathlib, json, re) |

| **Cross-Platform** | Windows, macOS, Linux compatible |

| **Test Coverage** | 33 unit tests, 81% code coverage (pytest) |

| **Documentation** | 788-line README in every generated project |



---



## 🚀 Quick Start



### Prerequisites



- Python 3.10 - 3.12 (uses `pathlib`, f-strings, match-case)

- Modern web browser for testing generated output

- HTTP server for local development (Python's built-in works)



### Installation



```bash

# Clone or download pwa_create.py

curl -O https://raw.githubusercontent.com/pkeffect/pwa-framework-generator/main/pwa_create.py



# Or just download the single file - no installation needed!

```



### Generate Your First Framework



```bash

# Interactive mode

python pwa_create.py



# Non-interactive mode

python pwa_create.py my-awesome-game



# With spaces (auto-sanitized)

python pwa_create.py "Space Shooter 2024"

```



### Run the Generated Project



```bash

cd my-awesome-game

python -m http.server 8000



# Open browser to http://localhost:8000

```



---



## 📂 Generated Project Structure



```

my-awesome-game/

├── index.html              # 119 lines - Entry point with CSP, SRI, ARIA

├── manifest.json           # 8 lines - PWA configuration

├── service-worker.js       # 60 lines - Cache versioning, fetch strategy

├── README.md               # 788 lines - Comprehensive documentation

├── .gitignore              # 6 lines - Standard exclusions

│

├── assets/                 # Media directory (empty scaffolding)

│   ├── icons/             # PWA icons (192x192, 512x512)

│   ├── audio/             # Sound effects, music

│   ├── textures/          # Sprites, backgrounds

│   ├── models/            # 3D models (optional)

│   └── shaders/           # WebGL shaders (optional)

│

├── css/

│   ├── main.css           # 89 lines - Reset, layout, canvas

│   └── ui.css             # 147 lines - Modals, sidebar, glassmorphism

│

└── js/

    ├── main.js            # 36 lines - Bootstrap & initialization

    ├── core/              # Engine layer (156 lines total)

    ├── scenes/            # State machines (52 lines total)

    ├── state/             # Data persistence (45 lines total)

    ├── ui/                # DOM interaction (120 lines total)

    └── utils/             # Helpers (43 lines total)

```



**Total Output:** 24 files, 1,460 lines of code, ~50KB uncompressed



---



## 🛠️ Usage



### Command-Line Interface



```bash

# Show help

python pwa_create.py --help



# Show version

python pwa_create.py --version



# Dry-run mode (preview without creating files)

python pwa_create.py my-game --dry-run



# Interactive mode (prompts for name)

python pwa_create.py



# Direct mode

python pwa_create.py my-game



# With special characters (auto-sanitized)

python pwa_create.py "My Game!"

# → Creates: my-game/

```



### Project Name Rules



| Rule | Description | Example |

|------|-------------|---------|

| **Length** | 1-50 characters | ✅ `my-game` ✅ `super-long-game-title-2024` |

| **First Char** | Must be alphanumeric | ✅ `g1` ❌ `-game` |

| **Allowed Chars** | Letters, numbers, hyphens, underscores | ✅ `my_game-2024` ❌ `my@game` |

| **Sanitization** | Auto-lowercase, spaces→hyphens | `My Game` → `my-game` |



### Python API



```python

from pathlib import Path

import sys



# Add script directory to path

sys.path.insert(0, str(Path(__file__).parent))



from pwa_create import create_framework, validate_project_name



# Validate name

try:

    clean_name = validate_project_name("My Game 2024")

    print(f"Sanitized: {clean_name}")  # "my-game-2024"

except ValueError as e:

    print(f"Invalid: {e}")



# Generate framework

success = create_framework("my-game")

if success:

    print("✅ Framework created!")

else:

    print("❌ Generation failed")

```



---



## 🧪 Testing & Development



### Running Tests



The generator includes a comprehensive test suite with 81% code coverage:



```bash

# Install test dependencies

pip install -r requirements-dev.txt



# Run all tests

python -m pytest tests/test_pwa_create.py -v



# Run with coverage report

python -m pytest tests/test_pwa_create.py --cov=pwa_create --cov-report=html



# Open coverage report

open htmlcov/index.html  # macOS

start htmlcov/index.html  # Windows

```



### Test Suite Coverage



- **Input Validation** (10 tests) - Path traversal, script injection, sanitization

- **Template Generation** (10 tests) - CSP, dark mode, cache limits, version metadata

- **Framework Creation** (6 tests) - File generation, directory structure, dry-run mode

- **Edge Cases** (4 tests) - Unicode, numeric names, length limits

- **Constants** (3 tests) - Version format, configuration bounds



### CI/CD



All commits are validated via GitHub Actions:

- ✅ Cross-platform testing (Ubuntu, Windows, macOS)

- ✅ Python 3.10, 3.11, 3.12 compatibility

- ✅ Unit test suite execution

- ✅ Generated project validation

- ✅ Security checks (CSP, eval(), imports)

- ✅ Feature verification (dark mode, cache limits, metadata)



---



## 📚 Documentation



### For Developers (Using Generated Frameworks)



Each generated project includes a comprehensive 788-line `README.md` with:



- 🏗️ Architecture breakdown

- 🎮 Quick start tutorial

- 📖 API reference for all modules

- 🐛 Troubleshooting guide

- 🚀 Deployment instructions (Netlify, Vercel, GitHub Pages)

- 🔒 Security documentation

- ♿ Accessibility guidelines



### For LLMs & Tool Developers



See [`DEVELOPER.md`](./DEVELOPER.md) for:



- Complete design pattern explanations

- Extension point documentation

- Common assistance scenarios

- Performance best practices

- Architecture deep dives



### For Auditors & Reviewers



See [`AUDIT.md`](./AUDIT.md) for:



- Feature comparison vs competitors

- Security posture analysis

- Performance benchmarks

- Code quality metrics

- Grading & recommendations



---



## 🎮 Examples



### Minimal Game Implementation



After generating a framework, edit `js/scenes/GameScene.js`:



```javascript

import { Renderer } from '../core/Renderer.js';

import { AssetLoader } from '../core/AssetLoader.js';



export class GameScene {

    enter() {

        this.canvas = Renderer.canvas;

        this.ctx = this.canvas.getContext('2d');

        

        this.player = {

            x: this.canvas.width / 2,

            y: this.canvas.height / 2,

            speed: 300

        };

        

        this.keys = {};

        window.addEventListener('keydown', e => this.keys[e.key] = true);

        window.addEventListener('keyup', e => this.keys[e.key] = false);

    }

    

    update(dt) {

        if (this.keys['ArrowLeft']) this.player.x -= this.player.speed * dt;

        if (this.keys['ArrowRight']) this.player.x += this.player.speed * dt;

        if (this.keys['ArrowUp']) this.player.y -= this.player.speed * dt;

        if (this.keys['ArrowDown']) this.player.y += this.player.speed * dt;

    }

    

    render() {

        this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);

        this.ctx.fillStyle = '#00ff00';

        this.ctx.fillRect(this.player.x - 10, this.player.y - 10, 20, 20);

    }

    

    exit() {

        // Cleanup

    }

}

```



Run with `python -m http.server 8000` and open `http://localhost:8000`.



### With Assets



Edit `js/main.js`:



```javascript

const MANIFEST = [

    { type: 'image', src: 'assets/textures/player.png', key: 'player' },

    { type: 'audio', src: 'assets/audio/jump.mp3', key: 'jump' }

];

```



Use in GameScene:



```javascript

render() {

    const playerImg = AssetLoader.get('player');

    if (playerImg) {

        this.ctx.drawImage(playerImg, this.player.x, this.player.y);

    }

}

```



---



## 🔍 Comparison



### vs. Create React App



| Feature | PWA Generator | Create React App |

|---------|---------------|------------------|

| **Setup Time** | 0.15s | 45-90s |

| **Footprint** | 50KB | ~300MB |

| **Dependencies** | 0 | 1,500+ packages |

| **Build Step** | None | Required (Webpack) |

| **Boot Time** | 28ms | 3-5s |

| **HMR** | No | Yes |

| **Framework** | Vanilla JS | React |

| **Best For** | Games, prototypes | Web apps |



### vs. Vite



| Feature | PWA Generator | Vite |

|---------|---------------|------|

| **Setup Time** | 0.15s | 15-30s |

| **Footprint** | 50KB | ~30MB |

| **Dependencies** | 0 | 200+ packages |

| **Build Step** | None | Required (Rollup) |

| **Dev Server** | Any HTTP | Built-in with HMR |

| **Production Build** | Copy files | Bundle + optimize |

| **Best For** | Zero-config games | Modern web apps |



### vs. Phaser



| Feature | PWA Generator | Phaser 3 |

|---------|---------------|----------|

| **Setup** | Single script | npm install |

| **Bundle Size** | 50KB framework | ~700KB library |

| **Learning Curve** | Low (vanilla JS) | Medium (Phaser API) |

| **Physics** | DIY | Built-in (Arcade, Matter) |

| **Rendering** | Canvas 2D | Canvas + WebGL |

| **Scene System** | Simple state machine | Full lifecycle engine |

| **Best For** | Education, jams | Production games |



---



## 🏆 Use Cases



### ✅ Perfect For



- **Game Jams** - Generate, code, deploy in hours

- **Prototyping** - Test ideas without setup overhead

- **Education** - Learn web development without tooling complexity

- **Portfolio Projects** - Showcase games without framework lock-in

- **Offline Tools** - PWA features for offline-first apps

- **Minimal MVPs** - Ship fast with zero dependencies



### ❌ Not Ideal For



- **Large Teams** - TypeScript + tooling better for collaboration

- **Complex Games** - Use Phaser, PixiJS, or Unity WebGL

- **Hot Module Replacement** - Use Vite or Webpack dev server

- **React/Vue Projects** - Use framework-specific generators



---



## 🔒 Security



### Generator Script



- ✅ Input validation with regex patterns

- ✅ Path traversal prevention (pathlib)

- ✅ No code execution from user input

- ✅ Exception handling for all file operations



### Generated Output



- ✅ Content Security Policy (CSP) headers

- ✅ Subresource Integrity (SRI) for CDN assets

- ✅ Input sanitization patterns

- ✅ Service worker cache versioning

- ✅ No eval() or unsafe code execution



---



## ♿ Accessibility



All generated frameworks are **WCAG 2.1 AA compliant**:



- ✅ Keyboard navigation (`Tab`, `Shift+Tab`, `ESC`)

- ✅ ARIA attributes on all interactive elements

- ✅ Focus trapping in modals

- ✅ Screen reader support

- ✅ Semantic HTML structure



---



## 🧪 Testing Generated Frameworks



```bash

# Generate test project

python pwa_create.py test-game



# Start local server

cd test-game

python -m http.server 8000



# Open browser

# Visit: http://localhost:8000



# Test PWA features (Chrome DevTools)

# 1. Application tab → Service Workers (should be registered)

# 2. Application tab → Manifest (should show name, icons)

# 3. Lighthouse audit (should score 90+ on PWA)



# Test offline mode

# 1. Load page once

# 2. DevTools → Network → Offline checkbox

# 3. Refresh page (should load from cache)

```



---



## 📈 Performance



### Generation Benchmarks



| Metric | Value |

|--------|-------|

| **Cold Start** | 147ms |

| **Warm Start** | 152ms |

| **Files Created** | 24 |

| **Directories Created** | 11 |

| **Lines of Code** | 1,460 |

| **Memory Usage** | <5MB |



*Tested on: Windows 11, Intel i7-10700K, Python 3.11*



### Generated Framework Benchmarks



| Metric | Value |

|--------|-------|

| **Boot Time** | 28ms |

| **First Paint** | 120ms |

| **Time to Interactive** | 180ms |

| **Lighthouse PWA Score** | 92/100 |

| **Lighthouse Performance** | 98/100 |



*Tested on: Chrome 120, throttled 4x CPU, Fast 3G network*



---



## 🤝 Contributing



Contributions welcome! This is a single-file generator, so changes are straightforward.



### Development Setup



```bash

# Clone repository

git clone https://github.com/pkeffect/pwa-framework-generator.git

cd pwa-framework-generator



# No installation needed - just edit pwa_create.py



# Test changes

python pwa_create.py test-output

cd test-output

python -m http.server 8000

```



### Code Quality



```bash

# Lint with flake8

pip install flake8

flake8 pwa_create.py --max-line-length=100



# Type check with mypy

pip install mypy

mypy pwa_create.py



# Format with black

pip install black

black pwa_create.py

```



### Adding Features



1. **New File Templates** - Add static method to `Templates` class

2. **Validation Rules** - Edit `validate_project_name()` function

3. **File Creation** - Add write operation in `create_framework()`

4. **Documentation** - Update generated README template



---



## 📝 License



**MIT License**



Copyright (c) 2024-2026 pkeffect



Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:



The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.



---



## 🙏 Acknowledgments



- **Inspiration:** Frustrated by complex build tools for simple game projects

- **Philosophy:** [Vanilla JavaScript](http://vanilla-js.com/) movement

- **Architecture:** Progressive Web App best practices from [web.dev](https://web.dev)

- **Accessibility:** WCAG 2.1 guidelines from [W3C](https://www.w3.org/WAI/WCAG21/quickref/)



---



## 📞 Support



- 🐛 **Bug Reports:** [GitHub Issues](https://github.com/pkeffect/pwa-framework-generator/issues)

- 💡 **Feature Requests:** [GitHub Discussions](https://github.com/pkeffect/pwa-framework-generator/discussions)

- 📧 **Email:** pkeffect@gmail.com

- 🌐 **Website:** https://internode.info/



---



## 🗺️ Roadmap



### v2.1.0 (Planned)



- [ ] TypeScript template option

- [ ] WebGL renderer template

- [ ] Touch input handler

- [ ] Multiple theme presets (dark, light, cyberpunk)

- [ ] Asset optimizer (image compression, audio conversion)



---






**Built with ❤️ for developers who value simplicity over complexity.**



[⬆ Back to Top](#pwa-game-framework-generator)