README.md

Navi

Android library to reduce boilerplate code for official Compose navigation.

Who is this for?

This is for you, if you want to follow Google's Compose navigation guidelines, but find its boilerplate code rather annoying. This library does not lock you into another third-party navigation library (framework?), but rather adds to what is already there. If there's something that Navi doesn't solve, you can still use Google's foundations.

Usage

Define a destination with just an object and Navi's Screen annotation:

@Screen(path = "welcome")
object WelcomeScreen

Navi will automatically generate the following code for you:

val WelcomeScreen.path: String                 // the simple path, as specified in annotation
val WelcomeScreen.route: String                // the complex pattern with arguments
fun NavGraphBuilder.welcomeScreen(/*...*/)     // to setup the composable
fun NavController.navigateToWelcomeScreen()    // to navigate
fun NavController.tryNavigateToWelcomeScreen() // to navigate without risk of crashes

Navi also supports arguments. It does not support Serializable or Parcelable, as recommended by Google.

@Screen(
    path = "profile",
    // args must be a data class, but doesn't have to be a nested class and name doesn't matter
    args = ProfileScreen.Args::class,
)
object ProfileScreen {
    data class Args(
        val id: String,
        val name: String?,
        val bar: List<Int>,
    )
}

Aside from properly adjusting the navigation extension functions, it will also generate factories to recreate the Args instance:

fun ProfileScreen.argsFrom(bundle: Bundle): ProfileScreen.Args
fun ProfileScreen.argsFrom(savedStateHandle: SavedStateHandle): ProfileScreen.Args
fun ProfileScreen.argsFrom(navBackStackEntry: NavBackStackEntry): ProfileScreen.Args?

See the demo app for a full example.

Installation

Navi is loaded from jitpack:

repositories {
    maven {
        url = uri("https://jitpack.io")
    }
}

Add the two dependencies to your app's build.gradle.kts file. Optionally, you may configure some behaviour of Navi.

dependencies {
    implementation("com.github.JanMalch.navi:navi-runtime:$navi_version")
    ksp("com.github.JanMalch.navi:navi-ksp:$navi_version")
}

// optional, displayed values are defaults
ksp {
    arg("naviExtFunNavigatePrefix", "navigateTo")
    arg("naviExtFunNavigateSuffix", "")
    arg("naviExtFunTryNavigatePrefix", "tryNavigateTo")
    arg("naviExtFunTryNavigateSuffix", "")
}

Credit

• Logo created with IconKitchen.