You've probably seen a million tutorials using build.gradle. But as you move into professional Kotlin development, you'll notice the file extension has changed to build.gradle.kts. That little .kts stands for Kotlin Script, and while it seems like a minor change, it completely changes how the build tool behaves. If you try to copy-paste Groovy code into a Kotlin DSL file, things break immediately.

// build.gradle.kts
dependencies {
    implementation 'com.squareup.moshi:moshi-kotlin:1.15.0'
    testImplementation 'org.jetbrains.kotlin:kotlin-test'
}

If you try to sync this, Gradle will throw a fit. You'll see an error like Expression expected or Unexpected token. It's frustrating because the code looks correct—you've seen it in a hundred StackOverflow answers. The problem is that you're writing Groovy in a Kotlin file.

Parentheses Are Not Optional

In Groovy, you can often omit parentheses when calling a function. implementation '...' works because Groovy is flexible (or lazy, depending on who you ask). Kotlin is not. In the Kotlin DSL, implementation is a function call. You cannot just place a string next to it and hope for the best.

Here is the fix. You have to wrap your dependency strings in parentheses:

// build.gradle.kts
dependencies {
    implementation("com.squareup.moshi:moshi-kotlin:1.15.0")
    testImplementation("org.jetbrains.kotlin:kotlin-test")
}

It feels like extra typing, but the payoff is huge. Because this is actual Kotlin code, you now get full IDE auto-completion. You don't have to guess if a property is named group or groupId; you can just hit Ctrl+Space and let the IDE tell you.

Handling Plugins the Modern Way

Another spot where learners usually trip up is the plugins block. In the old Groovy days, you'd see apply plugin: 'kotlin-android' scattered throughout the file. In the Kotlin DSL, we use the plugins { ... } block with a specific id syntax.

If you're trying to add a plugin and it's not resolving, make sure you're using the id()` function. I've seen people try to use the apply keyword inside the plugins block, which just won't work.

plugins {
    kotlin("jvm") version "1.9.20" 
    id("org.jetbrains.kotlin.plugin.serialization") version "1.9.20"
}

Notice the kotlin("jvm") shorthand? That's a helper function provided by Gradle for the most common Kotlin plugins. For anything else, use id("...").

Registering Custom Tasks Without the Magic

One of the most powerful parts of Gradle is creating your own tasks. In Groovy, tasks were often declared "magically" with a simple block. In Kotlin, we use tasks.register. This is "lazy" configuration, meaning Gradle won't actually create the task object unless it's actually needed for the build, which keeps your build times fast.

Let's say you want a task that prints a custom message before your tests run. You'd do it like this:

tasks.register("prepareTestEnvironment") {
    group = "verification"
    description = "Cleans up temporary test directories."
    
    doLast {
        println("Cleaning up /tmp/test-data... Done!")
    }
}

The doLast block is critical. If you put the println directly in the register block, it will execute every single time you run any Gradle command (including gradle help), because that block is for configuring the task, not executing it.

📋 Practical Task

Exercise: Implementing a Version-Logging Task and Dependency Sync

You are tasked with updating a build.gradle.kts file for a project that is migrating from Groovy to Kotlin DSL. Perform the following steps:

1. Fix the Dependencies: The following block is currently broken. Rewrite it using the correct Kotlin DSL syntax:

   dependencies {
       implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3'
       testImplementation 'org.junit.jupiter:junit-jupiter:5.10.0'
   }

2. Add a Plugin: Add the kotlin("plugin.serialization") plugin with version "1.9.20" to the plugins block.
3. Create a Custom Task: Register a new task named "printProjectDetails".
   • Assign it to the "help" group.
   • Inside a doLast block, print a message that says: "Building Project: [Project Name] Version: [Project Version]". (You can use the project.name and project.version properties).