Get started with Web Bundles

Share websites as a single file over Bluetooth and run them offline in your origin's context

Yusuke Utsunomiya

Kenji Baheux

Bundling a full website as a single file and making it shareable opens up new use cases for the web. Imagine a world where you can:

Create your own content and distribute it in all sorts of ways without being restricted to the network
Share a web app or piece of web content with your friends via Bluetooth or Wi-Fi Direct
Carry your site on your own USB or even host it on your own local network

The Web Bundles API is a bleeding edge proposal that lets you do all of this.

Browser compatibility

The Web Bundles API is currently only supported in Chromium-based browsers behind an experimental flag.

Introducing the Web Bundles API

A Web Bundle is a file format for encapsulating one or more HTTP resources in a single file. It can include one or more HTML files, JavaScript files, images, or stylesheets.

Web Bundles, more formally known as Bundled HTTP Exchanges, are part of the Web Packaging proposal.

A figure demonstrating that a Web Bundle is a collection of web resources. — How Web Bundles work

HTTP resources in a Web Bundle are indexed by request URLs, and can optionally come with signatures that vouch for the resources. Signatures allow browsers to understand and verify where each resource came from, and treats each as coming from its true origin. This is similar to how Signed HTTP Exchanges, a feature for signing a single HTTP resource, are handled.

This article walks you through what a Web Bundle is and how to use one.

Explaining Web Bundles

To be precise, a Web Bundle is a CBOR file with a .wbn extension (by convention) which packages HTTP resources into a binary format, and is served with the application/webbundle MIME type. You can read more about this in the Top-level structure section of the spec draft.

Web Bundles have multiple unique features:

Encapsulates multiple pages, enabling bundling of a complete website into a single file
Enables executable JavaScript, unlike MHTML
Uses HTTP Variants to do content negotiation, which enables internationalization with the Accept-Language header even if the bundle is used offline
Loads in the context of its origin when cryptographically signed by its publisher
Loads nearly instantly when served locally

These features open multiple scenarios. One common scenario is the ability to build a self-contained web app that's easy to share and usable without an internet connection. For example, say you're on an airplane from Tokyo to San Francisco with your friend. You don't like the in-flight entertainment. Your friend is playing an interesting web game called PROXX, and tells you that they downloaded the game as a Web Bundle before boarding the plane. It works flawlessly offline. Before Web Bundles, the story would end there and you would either have to take turns playing the game on your friend's device, or find something else to pass the time. But with Web Bundles, here's what you can now do:

Ask your friend to share the .wbn file of the game. For example the file could easily be shared peer-to-peer using a file sharing app.
Open the .wbn file in a browser that supports Web Bundles.
Start playing the game on your own device and try to beat your friend's high score.

Here's a video that explains this scenario.

As you can see, a Web Bundle can contain every resource, making it work offline and load instantly.

Building Web Bundles

The go/bundle CLI is currently the easiest way to bundle a website. go/bundle is a reference implementation of the Web Bundles specification built in Go.

Install Go.

Install go/bundle.

go get -u github.com/WICG/webpackage/go/bundle/cmd/...

Clone the preact-todomvc repository and build the web app to get ready to bundle the resources.

git clone https://github.com/developit/preact-todomvc.git
cd preact-todomvc
npm i
npm run build

Use the gen-bundle command to build a .wbn file.

gen-bundle -dir build -baseURL https://preact-todom.vc/ -primaryURL https://preact-todom.vc/ -o todomvc.wbn

Congratulations! TodoMVC is now a Web Bundle.

There are other options for bundling and more are coming. The go/bundle CLI lets you build a Web Bundle using a HAR file or a custom list of resource URLs. Visit the GitHub repo to learn more about go/bundle. You can also try out the experimental Node.js module for bundling, wbn. Note that wbn is still in the early stages of development.

Playing around with Web Bundles

To try out a Web Bundle:

Go to about://version to see what version of Chrome you're running. If you're running version 80 or later, skip the next step.
Download Chrome Canary if you're not running Chrome 80 or later.
Open about://flags/#web-bundles.
Set the Web Bundles flag to Enabled.

Enabling Web Bundles in about://flags
Relaunch Chrome.
Drag-and-drop the todomvc.wbn file into Chrome if you're on desktop, or tap it in a file management app if you're on Android.

Everything magically works.

The Preact implementation of TodoMVC working offline as a web bundle

You could also try out other sample web bundles:

web.dev.wbn is a snapshot of the entire web.dev site, as of 2019 October 15.
proxx.wbn: PROXX is a Minesweeper clone that works offline.
squoosh.wbn: Squoosh is a convenient and fast image optimization tool that lets you do side-by-side comparisons of various image compression formats, with support for resizing and format conversions.

Send feedback

The Web Bundle API implementation in Chrome is experimental and incomplete. Not everything is working and it might fail or crash. That's why it's behind an experimental flag. But the API is ready enough for you to explore it in Chrome. Feedback from web developers is crucial to the design of new APIs, so please try it out and tell the people working on Web Bundles what you think.

Send general feedback to webpackage-dev@chromium.org.
If you have feedback on the spec visit https://github.com/WICG/webpackage/issues/new to file a new spec issue, or email wpack@ietf.org.
If you find any issues in Chrome's behavior visit https://crbug.com/new to file a Chromium bug.
Any contributions to the spec discussion and tooling are also more than welcome. Visit the spec repo to get involved.

Acknowledgements

We would like to give a big shout-out to the wonderful Chrome engineering team, Kunihiko Sakamoto, Tsuyoshi Horo, Takashi Toyoshima, Kinuko Yasuda and Jeffrey Yasskin that worked hard contributing to the spec, building the feature on Canary and reviewing this article. During the standardization process Dan York has helped navigate the IETF discussion and also Dave Cramer has been a great resource on what publishers actually need. We also want to thank Jason Miller for the amazing preact-todomvc and his restless effort on making the framework better.