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.
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
images, or stylesheets.
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
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
- Uses HTTP Variants to do
content negotiation, which enables internationalization with the
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 she 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
.wbnfile of the game. For example the file
could easily be shared peer-to-peer using a file sharing app.
- Open the
.wbnfile in a browser that supports Web Bundles.
- Start playing the game on your own device and try to beat your friend’s high
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.
Currently Chrome 80 only supports unsigned bundles (that is, Web Bundles without
origin signatures). Bundling PROXX without signatures doesn’t work
well due to web worker cross-origin issues. Chrome is working on fixing this. In
the meantime, check out Dealing with Common Problems in Unsigned
to learn how to avoid cross-origin issues.
Building Web Bundles
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
npm run build
gen-bundlecommand to build a
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
lets you build a Web Bundle using a HAR file or a custom list of resource
URLs. Visit the GitHub
repo to learn more
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
Playing around with Web Bundles
To try out a Web Bundle:
chrome://versionto 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
Set the Web Bundles flag to Enabled.
todomvc.wbnfile into Chrome if you’re on desktop, or tap it in a file
management app if you’re on Android.
Everything magically works.
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 is a Minesweeper clone that works offline.
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.
Currently you can only navigate into a Web Bundle stored in a local file, but
that’s only a temporary restriction.
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.
We would like to give a big shout-out to the wonderful Chrome engineering team,
Kunihiko Sakamoto, Tsuyoshi
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.