The industry has systematically failed at modern offline web portability for the last two decades.If you want to distribute a complex, interactive manual or a heavy React dashboard for pure offline use, what are your options?
Historically, we had Microsoft's .CHM, which was great for documentation but turned into a malware nightmare and was abandoned. Then we got EPUB 3, which theoretically supports HTML5/JS, but in practice, e-readers aggressively sandbox it, block JS, and break CORS, making it useless for modern web apps. Single-file formats like .MHTML or browser extensions only work for a single flat page, instantly breaking when you have complex Single Page Application (SPA) routing.
Wrapping it in Electron? Now you are shipping a 150MB executable just to read a document. Out of absolute necessity, I built PWAA (Portable Web Application Archive).
The big problem was: 'How do we archive today’s rich Web?' Classic formats like PDF freeze static documents, completely destroying any interactivity, videos, or smooth navigation of Single Page Applications (SPA). EPUB is designed strictly for text and structured e-books, choking on heavy JavaScript. WARC (Web ARChive) is the gold standard for institutional preservation, but it's scarily complex for the average user and requires dedicated playback servers (Replay Servers).
What was missing in the market was a universal container: a file capable of storing all the complexity of modern frameworks (React, Vue, WebGL) and delivering a fast, interactive, and encapsulated experience with a simple double-click, supported by the native technologies of modern operating systems. This is where the PWAA format was born.
Currently, any interactive dashboard in React or document system requires a hosting server (Vercel, AWS, Netlify). PWAA frees engineers from the Cloud. The developer writes the code, packages it in a PWAA, sends it by email or USB drive, and the end user gets an exact and smooth experience, regardless of server shutdowns or connection drops.
Because the code thinks it's running on a real server, it completely bypasses CORS restrictions. Heavy manuals and heavy media work natively offline from a single double-clickable file. It even includes an SPA Fallback mechanism so virtual routing never hits a 404.
What is PWAA? PWAA is a new format engineered to pack an entire web app (HTML, CSS, JS, heavy media) into a standard PKZIP container. But here is the magic: the native reader never extracts it to the disk.
Instead of using file:/// protocols (which instantly trigger CORS blocks for fetching local JSON or ES6 modules), the PWAA reader maps the ZIP contents to memory and spins up an ephemeral in-memory HTTP server on 127.0.0.1.
Because your web code thinks it's running on a real cloud server, it completely bypasses CORS restrictions. Heavy SPAs (React, Next.js, Vue) work natively offline from a single double-clickable file.
The Architecture
I built the reference reader and builder in Go (Golang). Here are the core problems I had to solve:
1. The SPA Routing Problem (404s)
In a React/Vue app, navigation is virtual. If you refresh on /about, a static server throws a 404. I built an SPA Fallback algorithm into the in-memory server: if a file isn't found inside the ZIP, it instantly returns the bytes of index.html, letting the internal JS router take over.
2. The Video Streaming Problem (HTTP 416)
Browsers require Accept-Ranges: bytes to play .mp4 files. A standard on-the-fly ZIP extractor cannot easily jump to random bytes. I implemented a RAM-Buffering strategy that loads the requested media into physical RAM, transforming it into a bytes reader. This allows instant scrubbing on heavy video files with zero latency.
3. Absolute Security (Zero-Leak)
WebViews love to cache data. The PWAA reader is forced to run in an ephemeral sandbox session folder. The exact millisecond the reader window is closed, a graceful shutdown command obliterates the temporary folder. No cookies, no localStorage, and no cache are left on the host machine. I also injected a global JavaScript bodyguard that intercepts external links (https://) and forces them to open in the user's default external browser, keeping the PWAA window strictly isolated.
How to create a PWAA?
The core CLI (pwaa-builder) acts as a universal chameleon. It has three modes:
- Pack: Takes a static folder and wraps it into .pwaa.
- Build: Automatically detects your framework (package.json, .csproj), runs the install/build commands (e.g., npm run build), finds the dist folder, and archives it.
- Scrape: A recursive Web Crawler (built with Colly and GoQuery) that downloads a live website, rewrites the absolute DOM paths to relative offline paths, and generates an offline clone.
Open Core
The builder CLI is closed for now, but the full architectural spec, the VFS and reader logic, and the SDK are completely open-source. I want the community to see how the engine works, trust the security model, and even build their own native readers for macOS, Linux, or mobile. You can read the official Whitepaper and try the SDK here.
I’d love to hear your thoughts on this architecture. Is the era of static documentations finally over?
Top comments (0)