Composable-Nametag

한국어 README

Overview

Composable-Nametag is a debug tool that overlays the name of every @Composable function as a label on your screen.

Without modifying any existing code, the Kotlin Compiler Plugin (KCP) automatically injects labels at compile time.
See each Composable's name directly on screen, making layout debugging and code review faster.

Screenshots

Features

• Auto injection — The Compiler Plugin injects labels at compile time without touching your existing code.
• Zero overhead — Works via IR transformation at compile time, so disabling it has no runtime impact.
• Noise filtering — Only PascalCase Composables get labels; lambdas, remember, property accessors, etc. are ignored.
• Build safe — Unsupported Kotlin versions only disable the compiler plugin — the build always succeeds.

Installation

Option A. plugins {} block (standard)

Step 1. Make sure Maven Central is included in your plugin repositories in settings.gradle.kts:

// settings.gradle.kts
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()  // ← required
        google()
    }
}

Step 2. Apply the plugin in each Compose module's build.gradle.kts. It must be declared before the Compose plugin.

// feature/home/build.gradle.kts (Compose module)
plugins {
    id("io.github.dongx0915.composable.nametag") version "{library-version}" // Must be before the Compose plugin
    id("org.jetbrains.kotlin.plugin.compose") version "2.1.21"
    // ...
}

Note

No additional implementation dependency is needed — the plugin adds the runtime library automatically.

Option B. Convention Plugin

For projects using a Convention Plugin structure (e.g., build-logic):

Step 1. Make sure Maven Central is included in your repositories in build-logic/settings.gradle.kts:

// build-logic/settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        mavenCentral()  // ← required
        google()
        gradlePluginPortal()
    }
}

Step 2. Add the plugin artifact to your build-logic/build.gradle.kts:

// build-logic/build.gradle.kts
dependencies {
    implementation("io.github.dongx0915.composable.nametag:composable-nametag-gradle:{library-version}")
}

Step 3. Apply it inside your Compose Convention Plugin, before the Compose plugin:

// e.g., AndroidComposeConventionPlugin.kt
class AndroidComposeConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            pluginManager.apply("io.github.dongx0915.composable.nametag") // Must be before the Compose plugin
            pluginManager.apply("org.jetbrains.kotlin.plugin.compose")
            // ...
        }
    }
}

Requirements

• Android API 24 (Android 7.0) or higher
• Kotlin 2.1.21 ~ 2.3.20 (see Supported Versions)
• Jetpack Compose (BOM 2025.05.01 or compatible)
• JDK 17+

Usage

Enable the overlay

// Application class or wherever you want to toggle
ComposeDebugConfig.enabled = true

That's it. All @Composable function names will appear as labels on screen.

How It Works

Filtering Rules

Condition	Behavior
PascalCase @Composable	Label shown
camelCase (remember, modifier, etc.)	Skipped
Lambda / anonymous	Skipped
Property accessor	Skipped
__ prefix	Skipped

Kotlin Version Compatibility

The compiler plugin uses Kotlin IR internal APIs, so it is published per Kotlin version. The Gradle plugin auto-detects your Kotlin version and resolves the matching compiler artifact.

Kotlin Version	Supported
2.1.21	✅
2.2.0	✅
2.2.10	✅
2.2.20	✅
2.2.21	✅
2.3.0	✅
2.3.10	✅
2.3.20	✅

• Unsupported versions: Logs a warning once and disables only the compiler plugin. The build proceeds normally.

⚠️  compose-debug-overlay: Kotlin X.Y.Z is not supported.
    → Your build and app are NOT affected.

Tech Stack

• Kotlin 2.1.21 ~ 2.3.20
• AGP 8.6.1
• Compose BOM 2025.05.01
• Gradle 8.7

License

Apache License 2.0