A boilerplate free router concept for android, written in Kotlin


I am happy to help you with any problem on gitter, as fast as I can!
The goal is to investigate any reported issue within 2 days.

Why you should use Kompass

  • Powerful router which works great with MVP, MVVM and almost any other architecture
  • Boilerplate free routing: No more bundle.putInt(ARG_SOMETHING, something)
  • Very simple and clean architecture for applying custom transitions
  • Generic fragment transitions
  • Routing with multiple screen (which are called ships)
  • Kotlin


Step 1: Enable Annotation Processing

Add this at the top of your build.gradle

apply plugin: 'kotlin-kapt'

kapt {
    generateStubs = true

Step2: Add Kompass Dependencies
dependencies {
    implementation 'io.sellmair:kompass:0.0.10'
    implementation 'io.sellmair:kompass-annotation:0.0.10'
    kapt 'io.sellmair:kompass-processor:0.0.10'



I highly recommend having a look at the example app built with Kompass



Kompass makes extensive use of ship-vocabulary for its API's. Here are the main analogies:

  • The Kompass is the upper most object and contains ships
  • A Ship is the entity which can route to a certain Destination. This might represent a certain area of your
    activity where fragments can be loaded.
  • A Sail is the actual area where fragments can be placed in. Your activity therefore sets the
    sails for a certain ship, which then 'sails' to the destination.
  • A Destination represents one certain 'scene' of your app. It also holds all necessary arguments for
    the fragment/activity. For example: You might have a
    'LoginDestination', 'HomeDestination', 'SettingsDestination', ... in your application.
  • A Map knows how to display a certain Destination (meaning which Fragment or Activity to load for it).
    A map (AutoMap) is automatically created for you
  • A Cran knows how to push a Destination object into a Bundle. A Cran (AutoCran) is automatically
    created for you
  • A Detour can implement custom transitions for certain routes.
  • A DetourPilot knows about a bunch of Detours and knows when to apply which Detour

Create a Kompass

Creating the Kompass is very simple using the provided builder:

Create a Kompass: Trivial

This example is the most trivial Kompass that can be built. It accepts any object implementing
KompassDestination as Destination. We will talk about the .autoMap() part later.
It is easy, I promise :bowtie:

val trivialKompass = Kompass.builder<KompassDestination>(context)
                     .autoMap() // we will talk about this later

Create a Kompass: Real World Example

Here is a real-world example of Kompass, where MyCustomDestinationType is just a basic
sealed class and 'autoMap', 'autoCrane' and 'autoPilot' are extension functions automatically
generated by the KompassCompiler. But as you can see: It is very easy to create a Kompass object :blush:

val kompass = Kompass.builder<MyCustomDestinationType>(context)

Create your Destinations

Destinations are simple classes or data classes which hold very simple data like

  • Int
  • String
  • List< Int >
  • Parcelable

(Everything that can be represented inside android.os.Bundle)

Destinations are typically annotated with

@Destination(target = [MyFragmentOrActivity::class])

OR implement the KompassDestination Interface (if you do not want to use the Kompass-Compiler)

I consider it a good idea implemented a sealed superclass for groups of Destinations and restrict
the Kompass object to this superclass.

Example: Annotated Destination
class HomeDestination(val user: User)
Example: Implemented KompassDestination
class HomeDestination(val user: User): KompassDestination {
    override fun asBundle(): Bundle {
        val bundle = Bundle()
        // store user in bundle

Set sails to a Ship

Once your activity has started, you have to provide a sail for the ship which should route to certain
destinations. You can do this whenever you want to (even after you routed your ship to a certain
destination). The following example will show how the FrameLayout with id 'R.id.lisa_container' will
be used for the ship called Lisa as Sail:

class MainActivity : AppCompatActivity() {
    private lateinit var sail: KompassSail

    override fun onCreate(savedInstanceState: Bundle?) {
        // Step 1: Get the kompass instance (Dagger, Kodein, Singleton?, ...)
        val kompass = ...
        // Step 2: Get the ship called 'lisa'
        val lisa = kompass["lisa"]
        // Step 3: Set the sail and store the reference
        this.sail = lisa.setSail(this, R.id.lisa_container)

    override fun onDestroy() {
        // Step 4 Release the sail when no longer needed

Route to a Destination

Now it is time to route to a certain destination. The following example will show how the routing
for a login-screen could look like:

    companion object {
        const val MAIN_SHIP = "main"
    override fun onCreate(savedInstanceState: Bundle?) {

        val user = getUser()

        sail = kompass[MAIN_SHIP].setSail(this, container.id)
        kompass[MAIN_SHIP].navigateTo(if(user!=null) HomeDestination(user) else LoginDestination())

Recreate Destination from Bundle

One of the strongest parts of Kompass is the elimination of hassle with bundles and arguments.
You can easily recreate the original Destination from an intent or bundle using the automatically
generated extension functions.

Example: Fragment

If you routed to a certain fragment you can easily recreate the destination from the arguments Bundle

class HomeFragment: Fragment() {
    override fun onCreate(savedInstanceState: Bundle?) {
        val homeDestination = arguments.asHomeDestination() // Function was automatically generated
        val user = homeDestination?.user
        // ... Do something with your user object
Example: Activity
class HomeActivity: AppCompatActivity(){
    override fun onCreate(savedInstanceState: Bundle?, persistentState: PersistableBundle?) {
        val homeDestination = intent?.extras?.asHomeDestination()
        val user = homeDestination?.user
        // ... Do something with your user object


The Map

Maps contain informations about how to display a certain Destination. This can be done by
starting a new Activity or creating a new Fragment. If you want to use a custom Map element, add it to the KompassBuilder


The Cran

A cran knows how to pack a Destination object into a bundle. If you want to use a custom Cran,
add it to the KompassBuilder


The Detour / The DetourPilot

It is a very common thing to apply transitions when one fragment is replaced by another fragment.
A Detour can very easily implement such a transition genericly.

Consider we want every fragment to slide in, when entered and slide out, when exited. We just
have to write a Detour class like this:

    class FragmentSlide: KompassDetour<Any, Fragment, Fragment>{
        override fun setup(destination: Any,
                           currentFragment: Fragment,
                           nextFragment: Fragment,
                           transaction: FragmentTransaction) {
            currentFragment.exitTransition = Slide(Gravity.RIGHT)
            nextFragment.enterTransition = Slide(Gravity.LEFT)


Every Detour will automatically be applied if the types of 'destination', 'currentFragment' and 'nextFragment'
can be assigned from the current route and

       .autoPilot() // <-- will be available if you have some class annotaged with @Detour

is used!

AutoMap, AutoCran, AutoPilot

The functions


are automatically generated if possible.

  • .autoMap() will be available after you specified one target for at least one @Destination
  • .autoCran() will be available after you annotated at least one class with @Destination
  • .autoPilot() will be available after you annotated at least one class with @Detour


Kompass comes with an own back-stack. You should override your Activities 'onBackPressed' like:

    override fun onBackPressed() {
        if (!kompass.popBackImmediate())