https://github.com/fopwoc/nav3ksp
Multiplatform codegen library for typed navigation in Navigation 3
https://github.com/fopwoc/nav3ksp
jetpack-compose jetpack-compose-multiplatforms ksp multiplatform-kotlin-library navigation navigation3
Last synced: 6 months ago
JSON representation
Multiplatform codegen library for typed navigation in Navigation 3
- Host: GitHub
- URL: https://github.com/fopwoc/nav3ksp
- Owner: fopwoc
- License: mit
- Created: 2025-11-16T20:04:31.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2026-01-21T18:13:01.000Z (6 months ago)
- Last Synced: 2026-01-22T05:36:27.528Z (6 months ago)
- Topics: jetpack-compose, jetpack-compose-multiplatforms, ksp, multiplatform-kotlin-library, navigation, navigation3
- Language: Kotlin
- Homepage:
- Size: 847 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Nav3ksp
[](https://github.com/fopwoc/nav3ksp/actions/workflows/build.yml)
[](https://search.maven.org/search?q=g:io.github.fopwoc+nav3ksp)
Multiplatform codegen library for typed navigation in Navigation 3.
The library is designed to keep the same level of control that Navigation 3 gives to developers.
It solves the problem of writing a lot of boring and repetitive code that will link your Composable Views, typed navigation data classes, and entries to combine all of the above into NavDisplay.
It introduces several concepts:
* **Branch** - it's basically a NavKey, a Composable component representation with all its arguments. These are used to build the BackStack for Typed navigation.
* **Tree** - A collection of related Branches and other Trees that it includes. In collaboration with NavDisplay, it provides access to all associated Branches and subTrees via the BackStack.
By the way, this library can be used without KSP if you really like writing boilerplate by hand.
Somewhat inspired by the awesome Android library [compose-destinations](https://github.com/raamcosta/compose-destinations)
---
## Showcase
Android | iOS
:-: | :-:
|
---
## How to install
Firstly, you need to install the latest version of KSP plugin in your project.
```kotlin
plugins {
// ...
// check for the latest version here https://github.com/google/ksp/releases
id("com.google.devtools.ksp") version "2.3.3"
}
```
In `build.gradle.kts` at the `kotlin` block of your project, add dependencies to `commonMain`
```kotlin
kotlin {
// ...
sourceSets {
// ...
commonMain {
kotlin.srcDir("build/generated/ksp/metadata/commonMain/kotlin")
dependencies {
// ...
implementation("io.github.fopwoc:nav3ksp:1.0.1")
implementation("io.github.fopwoc:nav3ksp-annotation:1.0.1")
}
}
}
}
```
Add KSP plugin dependency to the `dependencies` block.
```kotlin
dependencies {
// ...
add("kspCommonMainMetadata", "io.github.fopwoc:nav3ksp-processor:1.0.1")
}
```
And finally, add somewhere in your `build.gradle.kts` this block to run codegen on every build.
Or not, then you have to call this job by hand.
```kotlin
tasks.named("preBuild") {
dependsOn("kspCommonMainKotlinMetadata")
}
```
---
I already said that, actually, you can use the library without any code generation, just as boilerplate "framework".
In this case, you don't need to install KSP plugin, all you have to do is add only this dependency to your `build.gradle.kts` project and have fun implementing abstract classes of all kinds.
```kotlin
sourceSets {
commonMain.dependencies {
// ...
implementation("io.github.fopwoc:nav3ksp:1.0.1")
}
}
```
---
## How to use
To begin, we need to declare an annotation that will represent our Tree
```kotlin
@Tree
annotation class RootTree
```
Then, for each View that will be part of this Tree, we must specify the Branch annotation and indicate the connection to the Tree
```kotlin
@Branch(RootTree::class)
@Composable
fun ExampleView() {
// ...
}
```
Finally, call NavDisplay, provide it with the generated NavTreeLayout and NavTreeBuilder of your Tree, and manually specify the first screen in BackStack. Or not just one, it's vararg.
```kotlin
val LocalBackStack = compositionLocalOf> {
error("No LocalBackStack provided")
}
@Composable
fun App() {
CompositionLocalProvider(
LocalBackStack provides RootNavTreeLayout.rememberTreeBackStack(RootNavTree.Example)
) {
NavDisplay(
navTreeBuilder = RootNavTreeBuilder,
backStackLocalComposition = LocalBackStack
)
}
}
```
That's it!
---
For more examples, you can see the 'example' module with a multiplatform app that shows a few usages of this library.
1) [Simple navigation](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/01-simple.kt) - Simple navigation.
2) [Back Handled](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/02-backhandled.kt) - Like simple navigation, but the back gesture is handled in the view.
3) [ViewModel](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/03-viewmodel.kt) - Example of how this lib handles view models.
4) [Arguments](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/04-arguments.kt) - Navigation with typed arguments.
5) [Nested](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/05-nested.kt) - Nested navigation with bottom bar and 3 views. Also, an example of handing backstack from another scope.
6) [Result](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/06-result.kt) - Navigation to form with result handling by another View.
7) [Manual](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/07-manual.kt) - Non-KSP usage, a-ka 'Boilerplate by hand'.
8) [Dialog](example/composeApp/src/commonMain/kotlin/io/github/fopwoc/nav3ksp/example/08-dialog.kt) - Dialog popup example via Scene and route metadata