PortableWeb Implementation Guide

This document is a non-normative guide for implementors of the PortableWeb format. It covers practical guidance for three audiences: content creators building .pweb bundles, AI tools generating PortableWeb output, and viewer developers building compatible viewers.

This guide accompanies the normative PortableWeb Format specification. In case of conflict, the normative specification takes precedence.

For Content Creators

Creating a basic bundle

A minimal .pweb bundle requires three files: mimetype, manifest.json, and an entry HTML file (typically index.html).

The easiest way to create a bundle is using the @portableweb/cli tool:

npx @portableweb/cli pack ./my-project/

The CLI handles correct ZIP ordering, uncompressed mimetype placement, and manifest validation automatically.

Writing the manifest

The manifest declares who the bundle is, what version of the spec it targets, and what capabilities it needs. Only declare capabilities you actually use — viewers present declared capabilities to the user before opening the bundle.

{
  "spec_version": "0.1",
  "id": "org.example.my-bundle",
  "version": "1.0.0",
  "title": "My Bundle",
  "entry": "index.html"
}

Keeping bundles self-contained

All assets (scripts, styles, images, fonts) must be included inside the bundle. External URLs are blocked by default. If your content currently loads from a CDN, download those assets and include them in the archive.

For AI Tools

This section is under development.

AI tools that generate interactive web content (games, simulations, presentations, educational materials) can output directly to .pweb format. Guidance on generating spec-compliant bundles programmatically will be added here.

Key considerations for AI-generated bundles:

Inline all dependencies — no external script or style URLs.
Generate a valid manifest.json with a unique id (use a reverse-domain scheme based on the tool's domain).
Declare only the capabilities the generated content actually uses.
Use the @portableweb/cli pack command or equivalent library to produce the final archive correctly.

For Viewer Developers