Bubblewrap: generate a Trusted Web Activity Android project from a PWA

What problem Bubblewrap solves, and who it is for

A Trusted Web Activity is an Android shell that opens a web page in a Chrome-backed view without browser chrome, provided the site and the app prove they belong to each other. Writing that shell by hand means creating an Android project, wiring the TWA library, setting the manifest, and generating the signing assets. Bubblewrap exists so that a web developer does not have to do any of that.

The repository describes itself as "a set of tools and libraries designed to help developers to create, build and update projects for Android Applications that launch Progressive Web App (PWA) using Trusted Web Activity (TWA)". The audience is therefore narrow and specific: teams that already have a working PWA with a web manifest and a service worker, and that want an Android package without maintaining an Android codebase.

It is not a PWA framework. It does not make a site installable, offline-capable or fast. If the web app is not already a PWA, Bubblewrap has nothing to wrap.

Three packages: core, cli and validator

The repository is a Lerna monorepo with three packages under packages/. bubblewrap/core is the JavaScript library that generates, builds and updates TWA projects. bubblewrap/cli is the command-line wrapper most users will touch. bubblewrap/validator is a library that checks TWA projects against quality criteria and compares them.

The root package.json describes the project as "Generate TWA projects from a Web Manifest". That single line is the data flow: the input is a Web App Manifest, the output is an Android project. The CLI reads the manifest, asks for or derives the package ID, the app name, the icon, the colors and the signing key, then writes out a Gradle project that includes the TWA integration.

The Dockerfile shows the runtime shape of the CLI. It installs @bubblewrap/cli globally with npm, then installs openjdk-17-jre, openjdk-17-jdk, lib32stdc++6 and lib32z1, and finally runs bubblewrap doctor with yes piped into it. That pipe is worth noticing: doctor is interactive, and the image answers its prompts automatically. The same Dockerfile writes a config file to /root/.bubblewrap/config.json with a jdkPath key pointing at /usr/lib/jvm/java-17-openjdk-amd64 and an androidSdkPath key set to an empty string. The empty androidSdkPath is the tell that the Android SDK is not bundled and is expected to be supplied later.

Installing Bubblewrap and building a first APK

The README states one requirement: Node.js 14.15.0 or above. The root package.json sets a stricter engine field of node >=18.0.0, which is what the monorepo itself is developed against. If you are installing the published CLI rather than building from source, the README's number is the one it advertises.

The Dockerfile gives a working global install command, and it is the shortest path to a usable binary:

npm install -g @bubblewrap/cli

After that, the CLI expects a JDK and an Android SDK. The Dockerfile shows the shape of the config file the CLI reads, written to /root/.bubblewrap/config.json:

{ "jdkPath": "/usr/lib/jvm/java-17-openjdk-amd64", "androidSdkPath": "" }

With the toolchain in place, the doctor command checks the environment. The Dockerfile runs it non-interactively:

yes | bubblewrap doctor

A human running this will see prompts about missing components and can let the CLI fetch what it needs. Once doctor is satisfied, the README points to the Trusted Web Activity Quick Start Guide and the bubblewrap/cli documentation for the actual project creation flow. The README does not reproduce those steps, so the exact prompts and flags belong to that guide rather than to this page.

Where Bubblewrap stops being the right tool

The most important limitation is the one the project states itself: the README ends with "This is not an officially supported Google product." Despite the GoogleChromeLabs organization and the Apache-2.0 license, there is no support contract behind it. Teams that need a vendor to escalate to should read that line twice.

The second limitation is structural. A TWA renders your web content. Anything that requires native Android APIs, background services, Bluetooth, file system access beyond what the web platform exposes, or a UI that is not your website, is outside what this generates. If you need those, you want a native or cross-platform Android project, not a wrapper.

The third is the build environment. Bubblewrap is not a hosted service. The Dockerfile is a fair summary of what a build machine needs: Node.js, a JDK, and Android SDK libraries. The androidSdkPath key is written empty in that file, meaning the image alone does not complete the setup. Anyone expecting a single install command and a finished APK will be disappointed.

Finally, the repository's own package.json has not kept pace with the CLI. The root version is 0.4.3 while the most recent release is v1.25.0, so the version number you see at the top of the monorepo does not describe the CLI you install.

PWABuilder is the GUI alternative, and it shares the same core

The README names the alternative directly under "Getting started with GUI tools": PWABuilder at pwabuilder.com, which it says "is powered by Bubblewrap and uses the same underlying core." That is an unusually candid pointer, and it changes the comparison. This is not Bubblewrap versus a competing implementation of TWA packaging. It is the same generation engine behind two front ends.

The practical difference is where the work happens. PWABuilder is a web interface: you give it a URL, it produces a package, and the Android toolchain runs on someone else's machine. Bubblewrap is the CLI and library: the toolchain runs on yours, the project is a set of files you can commit, diff and rebuild in CI, and you can script it because bubblewrap/core is importable JavaScript.

Choose the CLI when you want the generated Android project in version control and a repeatable build. Choose the GUI when you want one APK and never intend to touch Gradle. If the PWA's manifest is incomplete, the GUI will surface that as a form to fill in; the CLI will surface it as a prompt or an error.

Maintenance, releases and licence

The last push to the default branch was on 2026-07-31, the same day as the v1.25.0 release. The previous releases were v1.24.0 on 2025-09-25 and v1.24.1 on 2025-09-29. The gap between the 1.24 line and 1.25.0 is roughly ten months, so the release cadence is not fast, and the repository is not archived.

The README lists a public monthly office hours session, hosted on the first Thursday at 5PM London time, with a calendar link and a meeting link, plus a Chromium Slack channel for discussion. That is the upgrade channel in practice: there is no documented long-term support branch, and the README does not describe a deprecation policy or a rollback procedure for a generated project.

Licensing is Apache-2.0 at the repository root, and the README points to LICENSE for the full text. Apache-2.0 permits commercial use and modification and includes a patent grant. The README carries a disclaimer that this is not an officially supported Google product, which is a support statement rather than a licence term. Whether the trademark or the Play Store listing obligations apply to your app is a question for your own counsel, not something the repository answers.

Editorial conclusion

Adopt Bubblewrap if you already run a PWA and want an Android package that loads it in a Trusted Web Activity, and you are willing to install the JDK and Android SDK on the build machine. Do not adopt it if your app needs native Android APIs, or if you want a hosted build with no local toolchain. Before committing, verify that your web manifest and Digital Asset Links setup pass bubblewrap doctor and a local build on your own machine.

Frequently asked questions

Official sources

1. GoogleChromeLabs/bubblewrap on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases