Migrating Compose Destinations To 1.5.0-beta

A practical migration guide considering the latest breaking changes

In one of my previous articles, I presented the great Compose Destinations library to you which drastically facilitates the navigation implementation in our Jetpack Compose-driven Android apps.

However, as time flies by the library received some updates. With the recent update to version 1.5.0-beta some breaking changes came into play that I want to talk about in this article by migrating the example scenario from the previous article.

1. Update your dependencies

Assuming you followed the previous article you should update the dependency of the library to at least the following:

Just to mention, if you meanwhile updated Kotlin to version 1.6.20, don’t forget to adapt the KSP dependency:

Now that we updated to the latest version, building the project will print out some warnings.

So let’s take a look at what has changed, what is required to adapt to get rid of these, and make use of the newly introduced features.

2. Declaring Destinations

Let’s reconsider the scenario from the previous article. We had a simple Android app with bottom navigation that contained a HomeDestination with a sub-route SettingsDestination and a DetailsDestination.

Before version 1.5.0-beta we declared our destinations in the following way:

Out of the box, Compose Destinations adds all destinations to a NavGraph called root. By declaring a destination with @Destination and setting the start parameter to true, the respective destination is set as the entry point of the NavGraph.

1.1 What has changed?

With the introduction of Compose Destinations 1.5.0-beta, the definition of NavGraphs got reworked. Without further configuration, our destinations still get implicitly added to the root NavGraph.

However, while the start parameter of the @Destination is still present, it is marked as deprecated.

From now on we use the new NavGraph annotation instead to set this parameter. Because the implicit NavGraph is named root, the annotation automatically gets generated to @RootNavGraph.

So how can we now set the HomeScreen or rather the HomeScreenDestination to the entry point of the RootNavGraph? Take a look at the following code snippet:

As you can see, the start parameter just moved from the @Destination annotation to the @RootNavGraph annotation.

Note: Because all the destinations without a NavGraph annotation get implicitly added to the RootNavGraph, we just need the annotation at the starting point. Of course you could add it to all destinations you would like to have in your RootNavGraph if you feel like that give you a better overview.

3. Creating additional NavGraphs

Prior 1.5.0-beta, declaring additional NavGraphs was done via the navGraph parameter of a @Destination as you can see in the following code snippet:

The DetailsNavGraph was then generated if at least one @Destination got annotated with the respective name. The drawback of that feature was that we had no direct type safetyness on the NavGraph.

With 1.5.0-beta we now create our own NavGraph annotation that fixes this issue. We can create a new annotation by defining a annotation class in the following way:

Because the DetailsavGraph should be nested inside our RootNavGraph, we add the @RootNavGraph to the new DetailsNavGraph annotation class.

The name of the class will be automatically used as an annotation that can be set to our destinations just as we did it previously with the @RootNavGraph annotation.

Additionally, we need to add val start: Boolean = false to the annotation to be able to set a destination as the entry point of our new NavGraph.

Now that we declared our DetailsNavGraph, we can add our DetailsScreen to be a part of that NavGraph and also being the start destination with the respective annotation like you can see in the following code snippet:

4 Conclusion

Because my previous article on the Compose Destination library was written based on version 1.4.2-beta, I wrote this one to avoid confusion at some points and to provide some quick hints on what you need to adapt to get the library up and running.

Therefore, in this article, we took a look at the changes in the version 1.5.0-beta of the Compose Destinations library.

In my opinion, the changes bring some real value to the library, not forgetting to mention the newly introduced nullability of all destination arguments (which was previously not the case).

I am very excited about the future of this library and am still very enthusiastic. I can only recommend everyone to try it in their Jetpack Compose project if you use are still using the official Navigation Compose library.

I hope you had some takeaways, clap if you liked my article, make sure to subscribe to get notified via e-mail, and follow for more!