Guidance on migrating an Android WebView-based app to Chromium

[angad]

Hello Chromium Developers,

I’m currently working on an Android application (“Surf”) that is built on top of the Android WebView. We are exploring a migration path to Chromium in order to gain deeper control over rendering, navigation, networking, and JavaScript execution beyond what WebView exposes.

I’ve gone through the Chromium documentation around the content module, Content Shell, and Android targets (content_shell_apk, chrome_public_apk, system_webview_apk), and I’d like guidance on the correct and supported way to proceed.

Specifically, I’m trying to understand the following options and their feasibility:

1. Using Chromium as a reusable SDK

   • Is it supported (or planned) to consume Chromium or Content Shell artifacts as an .aar or library and integrate them into an existing Android app?

   • If not, is there an architectural reason Chromium is intentionally not exposed this way?

2. Directly integrating Chromium into an existing app

   • Is there any supported approach to embedding Chromium’s content layer into an existing Android application (beyond WebView), while reusing an existing Java/Kotlin app codebase?

   • Or is Chromium intended to be consumed only by building a full browser-style application around it?

3. Building a separate Chromium-based app

   • If the recommended approach is to build a separate Chromium-based application (similar to Content Shell or Chrome), is the expectation that application-specific logic (UI, navigation, business logic) should be implemented directly inside the Chromium codebase as an embedder?

   • In this case, what is the recommended way to migrate or reuse existing app logic?

4. Content Shell as a foundation

   • Is Content Shell intended only as a testing/sample embedder, or is it a valid starting point for building a production-grade embedded browser application?

   • Are there examples or references of production embedders built directly on top of //content on Android?

Overall, I’m trying to determine whether:

• Chromium can be consumed inside an existing Android app, or

• The app must instead be rebuilt as a Chromium embedder.

Any guidance, documentation pointers, or architectural clarifications would be greatly appreciated. I want to ensure we proceed in a way that aligns with Chromium’s intended design and long-term maintenance model.

Thank you for your time and for all the work that goes into Chromium.

Best regards,

Angad

[Torne (Richard Coles)]

On Wed, 14 Jan 2026 at 11:22, angad <t403...@gmail.com> wrote:

Hello Chromium Developers,

I’m currently working on an Android application (“Surf”) that is built on top of the Android WebView. We are exploring a migration path to Chromium in order to gain deeper control over rendering, navigation, networking, and JavaScript execution beyond what WebView exposes.

I’ve gone through the Chromium documentation around the content module, Content Shell, and Android targets (content_shell_apk, chrome_public_apk, system_webview_apk), and I’d like guidance on the correct and supported way to proceed.

As one of the WebView maintainers I can take a reasonable go at answering these as this is a topic that comes up from time to time, but don't take this as especially authoritative about the Chromium project as a whole; I'm not in charge. :)

Specifically, I’m trying to understand the following options and their feasibility:

1. Using Chromium as a reusable SDK

   • Is it supported (or planned) to consume Chromium or Content Shell artifacts as an .aar or library and integrate them into an existing Android app?

   • If not, is there an architectural reason Chromium is intentionally not exposed this way?

No, there's no support for this. It's not exposed this way because none of the projects that are developed as part of the Chromium source tree require it or would particularly benefit from it. Android WebView is the only project built from Chromium which is used as a library, but it's designed to be used specifically as a library by the Android OS/framework itself to implement the API surface exposed by the framework, not to be used by apps directly, and so also would not benefit from the code being structured this way.

1. Directly integrating Chromium into an existing app

   • Is there any supported approach to embedding Chromium’s content layer into an existing Android application (beyond WebView), while reusing an existing Java/Kotlin app codebase?

   • Or is Chromium intended to be consumed only by building a full browser-style application around it?

Whatever you do, there is no way to continue using existing app code which is written to use the Android WebView APIs. The way that these APIs are implemented is very specifically tied to the Android framework implementation and there's no practical way to make these APIs do anything other than invoke the OS's WebView implementation.

There is nothing technically *preventing* you from integrating the //content layer into an existing application if you are writing the parts of the app which interact with Chromium from scratch (or just rewriting them) - this is in practice how //content is already being used by the Chromium browser, WebView, and other build targets. But, as mentioned above there's no explicit *support* for this either - there is no guarantee of API stability between versions, and there's no provided build target that just builds a completely selfcontained AAR to be consumed by an app that *isn't* also being built by the Chromium build system. Depending on your use case, it's also possible that //content by itself may be too low-level or not provide all the features that you may want - the //chrome, //android_webview, etc targets also consume various things from //components that build on top of //content (which can be reused, but is more things you'd need to do beyond just considering //content), and also implement various things within those directories that you might want to reuse but which aren't currently separated out into explicitly reusable targets in //components.

So, there's no particular app architecture that is *required* in order to do this, but you are largely on your own if you are going to do something that's very different than how the other consumers of //content in the Chromium tree work, and the more complex your integration is, the more difficult it's likely to be in future to update to a newer version of Chromium where the specific build targets and APIs that you're relying on may have changed.

1. Building a separate Chromium-based app

   • If the recommended approach is to build a separate Chromium-based application (similar to Content Shell or Chrome), is the expectation that application-specific logic (UI, navigation, business logic) should be implemented directly inside the Chromium codebase as an embedder?

   • In this case, what is the recommended way to migrate or reuse existing app logic?

If your app is going to be mostly based on Chromium and you don't have a lot of existing code you want to reuse then this is probably the easiest option in practice - fork the Chromium repository, add your own embedder in a new top-level directory, and use our existing build system to directly depend on the parts of the Chromium code that you need. Using your existing app code in this case would mean throwing out your current build system and instead writing GN build files to build that code, and adopting our mechanisms for depending on any existing JAR/AAR libraries that your code depends on that don't already exist in the Chromium tree. This might not require many changes to the actual *code*, though - it's mostly just going to be about adopting the Chromium build system.

You could instead just try to build the parts of Chromium that you need into a JAR/AAR and then have your app continue to be built the way it does now, separately from Chromium. The Chromium GN build configuration does support defining this kind of library target to "export" for usage elsewhere - see the definition of the dist_aar template here. But as I said above there's no predefined build target for this and exactly what you would need to include in such a library would be up to your app's specific requirements; you'd have to figure out what specific things in Chromium your library needs to depend on to be useful and complete for your app's purposes.

1. Content Shell as a foundation

   • Is Content Shell intended only as a testing/sample embedder, or is it a valid starting point for building a production-grade embedded browser application?

Content Shell is just a testing utility and a general usage example for the //content API. It's likely to be a better starting point for building your own //content embedder than starting entirely from scratch since the //content API is quite complex and starting from something that builds and can render web pages is going to be helpful, but it is nowhere near being a production-grade browser app; it lacks many features that are supported in the Chromium browser or in WebView, and there are no guarantees about security as it's primarily used for testing.

1. • Are there examples or references of production embedders built directly on top of //content on Android?

The Chromium Embedded Framework (CEF) is the out-of-tree //content embedder that I'm most aware of but it doesn't support Android.

In the past various projects maintained libraries based on parts of the WebView code to be embedded by Android apps, for example Crosswalk, but all the public/open source projects doing this that I'm aware of have been discontinued for a long time. These were generally based on the "WebView test shell" which is a standalone app similar to Content Shell used for testing that is built on top of *most* of the //android_webview code but does not integrate with the Android framework APIs and does not use the same method of rendering pixels into the app UI.

As with my answers to all the above questions about //content, the WebView test shell *also* doesn't provide stable APIs across different versions, doesn't provide a selfcontained library target (it's an app), isn't suitable as a production-quality browser without a great deal of additional work on top of it, and can't directly replace use of the system WebView APIs in existing app code.

There are several still-active libraries that are implemented this way but all the ones I'm aware of are either commercial products or are not publicly available at all and are just used by the maintainers' own apps. They are more popular for Android apps distributed in China where the system WebView isn't usually updatable, but they're much less common for apps distributed via the Play Store in the rest of the world, since embedding the Chromium code this way significantly increases the size of your app and creates a lot of ongoing maintenance costs, even if some of the cost might be borne by the specific library's vendor.

Overall, I’m trying to determine whether:

• Chromium can be consumed inside an existing Android app, or

• The app must instead be rebuilt as a Chromium embedder.

Other than exactly what the build system looks like (i.e. do you fork Chromium and add a build target that exports a library with the bits you want to consume and then build your app code against that library separately, or do you fork Chromium and build your app code as part of the Chromium build) I don't think there is really much difference between these things to begin with.

There isn't really any explicit support for either approach, they're both going to run into the same issues with APIs changing between versions, and they're both likely to be a very large amount of work for the app to "keep up" with Chromium development and security updates. So, I don't think there's really any particular recommendation here - you are setting yourself up for a lot of challenging work no matter what architectural decisions you make.

Any guidance, documentation pointers, or architectural clarifications would be greatly appreciated. I want to ensure we proceed in a way that aligns with Chromium’s intended design and long-term maintenance model.

Thank you for your time and for all the work that goes into Chromium.

Best regards,

Angad

--
--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev
---
You received this message because you are subscribed to the Google Groups "Chromium-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to chromium-dev...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/chromium-dev/4dd6fcaa-96ed-4ada-a37c-515f370fcc7an%40chromium.org.