Jetpack Compose Accompanist — An FAQ.

Accompanist is a group of libraries that aim to supplement Jetpack Compose with features that are commonly required by developers but not yet officially supported in Jetpack Compose AndroidX libraries.

Accompanist is a labs-like environment for new Compose APIs. We use it to help fill known gaps in the Compose toolkit, experiment with new APIs and to gather insight into the development experience of developing a Compose library. The goal of Accompanist is to not exist. We want to upstream the libraries into the official toolkit, at which point they will be deprecated and removed from Accompanist.

Currently in Accompanist you can find libraries for Flow Layouts, Pager, Navigation Transitions, Swipe Refresh and more.

We frequently get asked a lot of questions about this library and so thought we could write a post to answer some of the most asked Accompanist questions.

Why does Accompanist exist?

A major reason for Accompanist’s existence is the fact that AndroidX does not allow experimental API usage across different modules. There were features we knew we could develop that wouldn’t be allowed in AndroidX. For example, navigation transitions require some experimental animation APIs so cannot be built within navigation-compose but can be built in Accompanist.

For standalone features, you might think, why not just mark the APIs as Experimental in AndroidX? When we add an experimental API to AndroidX, we are confident that the feature will exist in some form but possibly the API will change shape. We also try to have them out of Experimental as fast as possible, we know this doesn’t always happen but that is the goal. When we need them to be longer lasting as experimental or aren’t sure the feature makes sense, Accompanist is where they live.

This table summarizes the different rules that apply to different API locations. These rules are further detailed later in the post as well.

The goal of Accompanist is to eventually not exist, that as the AndroidX Compose libraries mature & stabilize, all functionality is upstreamed.

History

Another major part of the reason Accompanist exists is history. Accompanist was initially developed by Chris Banes and the Compose team during the early days of Compose. The Compose team were developing the Compose samples and as Compose was still in very early development, there were a lot of gaps in the feature set they required. Both from Compose itself but also from a lack of early support by other libraries. The team wrote a lot of code to make the apps work. Accompanist was created as a place to release this code for others to use. The first ever Accompanist library was a Coil wrapper for loading images asynchronously. Window insets handling was added next, followed by AppCompat theme adapter and then in 0.7.0 a further 4 libraries were added. Pager, Pager Indicators, System UI Controller and Flow Layouts. This was also when the library was moved from Chris’s personal account to an official Google library and the package name was changed from dev.chrisbanes.accompanist to com.google.accompanist accordingly. By this point, multiple members of the Compose team and the community were working on and contributing to the library and it grew from there.

Currently we have 12 active libraries and 1 deprecated library (Insets as it has been upstreamed) in Accompanist. Our goal is to take the most used features from Accompanist and upstream them into the main Compose libraries. This was originally successfully done with the first Accompanist library, Coil and then was subsequently done with Insets to Compose Foundation. We will be ramping up our upstreaming efforts over the next few Compose releases, APIs might change during upstreaming but we are committed to providing an easy migration path for all users of Accompanist. With the updating of the Compose Roadmap you can see, the next API that is being upstreamed is Flow Layout.

What is upstreaming?

The main Compose libraries are developed in AndroidX, our open source repository of Android libraries. This group of libraries is known as Jetpack. Accompanist however is developed separately from the main Compose libraries. When we talk about “upstreaming”, we mean to move the development from Accompanist to the main Compose libraries as an official feature.

Why does it live in GitHub and not AndroidX?

Accompanist is developed on GitHub, in the open. The main reason for this is just history, as stated above. What started as a library developed by one author, grew and turned into a collection of libraries developed by multiple authors. There are some important advantages and reasons it remains on GitHub however.

AndroidX Experimental APIs

As detailed above, AndroidX does not allow cross module experimental APIs. This means, Compose Navigation wouldn’t be able to use the experimental Compose Animation APIs that make navigation transitions possible. Bottom Sheet Navigator wouldn’t be able to use the experimental Material APIs, and so on. As these are features we know the community needs, developing them in Accompanist is ideal. It allows us to get the feature out to developers without having to wait for the version of Compose that removes the experimental annotation.

Binary Compatibility

AndroidX also has strict binary compatibility rules that make changing APIs difficult without bumping major version numbers. These rules exist for a good reason, as APIs changing all the time would make developing with them a burden. Accompanist tries to not change the API structure drastically between releases but does not guarantee it. When we release an API in AndroidX, we might change it but our hope is we don’t have to. In cases where we aren’t sure about an API, we mark it as experimental. In Accompanist we are free to experiment even more which is great for when we aren’t sure about something without community feedback.

Community Contributions

AndroidX has quite a steep onboarding path before your first contribution, it is also difficult to build and run locally. GitHub allows for much easier community contributions, which we encourage. Because we develop in a system already familiar to developers, we get a lot more contributions than we would otherwise, for example Navigation Material was developed by Jossi Wolf before he joined Google!

Insight into the Compose experience

Developing on GitHub gives us valuable insight into what issues external developers face. By just staying in AndroidX, we often miss issues that seem obvious to external developers. By developing in GitHub where most other external libraries are developed, we spot issues much earlier.

How often do you release Accompanist?

We release a new version of Accompanist for every release of Compose.

Is Accompanist safe to use in production?

We believe it is! Accompanist is used by just under 30% of apps that use Compose on the Play Store and is still growing. It is also used by the Play Store app itself, and several other Google apps. Accompanist is no different to any other library you might import into your app. We make every effort to maintain it, fix bugs and stay on top of issues. You should always review the source code yourself to see if you are happy with it before adding it to your app, the same as any other library you use.

Is it going to just disappear tomorrow?

Our goal is to upstream the most used features into the main Compose library once we can, and we are going to be doing that with more libraries soon. We won’t just instantly remove them from Accompanist though. Any time a library is upstreamed, we keep a deprecated version of it in Accompanist for at least one stable release of Compose. We will also provide a migration guide or @ReplaceWith annotations to make moving from the Accompanist version, to the official version easy.

Why do I always have to match my Accompanist version to my Compose version?

You should always match your Compose UI version and Accompanist version. We always display the latest release for each supported version of Compose in the Accompanist readme. This is especially important for major (x.0.0) and minor (1.x.0) releases as if you use a newer Accompanist with an older version of Compose UI, your project will be upgraded to the new version of Compose UI transitively. For example:

Accompanist 0.26.0-alpha builds against Compose UI 1.3.0-alpha02. If your project used Compose UI 1.2.1 and you added Accompanist 0.26.x, you would be upgrading your Compose version from 1.2.1 to 1.3.0-alpha02. This could bring breaking changes to your project that you weren’t expecting!

How do you handle Compose Compiler upgrades?

Our current strategy is that for alpha/beta/rc releases of the Accompanist, we will always use the latest release of the Compiler, whether it is stable or not. For Accompanist releases that match stable releases of Compose UI, we will use the latest stable version of the compiler. We will also keep the latest stable version of Accompanist up to date with the latest stable compiler releases.

For example at the time of writing, Compose UI 1.2.1 is stable and we have Accompanist 0.25.1 matching it. 0.25.1 is built with Compose Compiler 1.3.0 which uses Kotlin 1.7.10. When the next stable compiler release happens, we will create a new version of Accompanist that still targets Compose UI 1.2.1 but builds with the new compiler so that you can upgrade the Kotlin version of your project.

Once Compose UI 1.2 is no longer the latest stable version, we will no longer provide compiler updates for its matching Accompanist version.

Do you accept new features/libraries from the community?

Without a Google owner working with you, no, we do not anymore. Now that Compose is out and stable, we want the library ecosystem to grow! We don’t want every library ending up in Accompanist instead, this is just confusing for developers. We would love for you to release your feature as a library of its own. If you do think your library makes sense in Accompanist, please open an issue first to discuss with us and we may be able to find an owner to work with you.

We definitely accept and encourage bug fixes and improvements to the existing libraries. If you have a large contribution, like any open source repository, it is always best to reach out to us via GitHub issues, to check if we can support its inclusion.

Will you be releasing more Accompanist libraries?

There was one just released to help with adaptive layouts, but that is the only new library planned at the moment. Separately to Accompanist, we have also published and are developing Horologist to help in a similar way with Compose for Wear.

We know having a separate library outside of AndroidX is confusing for developers and creates extra work during a migration though so we only want to add new libraries to Accompanist where there is a clear path to upstreaming and the experimentation in Accompanist is clearly required.