kotlin-project-setup

Kotlin Project Setup

When to Use

Use this skill when:

• The user is initializing a new Kotlin project and needs to choose between Gradle (Kotlin DSL), Maven, or other build tooling with proper Kotlin compiler plugin configuration
• The user wants to set up a production-ready Kotlin project with proper multimodule structure, code quality gates, coroutines support, and serialization
• The user is migrating a Java project to Kotlin and needs guidance on coexistence configuration, @JvmStatic, @JvmOverloads, and incremental migration strategy
• The user needs to configure Kotlin for a specific runtime target -- JVM backend (Spring Boot, Ktor, Quarkus), Android, Kotlin/JS, or Kotlin Multiplatform Mobile (KMM)
• The user wants to establish team-wide conventions including opt-in API configuration, explicit API mode, compiler flags, and lint rules using detekt or ktlint
• The user is setting up CI/CD pipelines that compile Kotlin correctly with incremental compilation, build caching, and parallel execution
• The user wants to configure the Kotlin compiler for strict null safety, progressive mode, or specific JVM target bytecode version

Do NOT use this skill when:

• The user needs help with Kotlin syntax, language features, or algorithms -- those are language learning questions, not project setup
• The user is configuring Android-specific concerns like Gradle AGP versioning, ProGuard/R8 rules, or Android SDK targets -- check the android-project-setup skill
• The user needs Kotlin Multiplatform project scaffolding with shared modules for iOS/Android -- check the kotlin-multiplatform skill if available
• The user is asking about deploying a Kotlin application (Docker, Kubernetes, cloud) -- check the deployment skills in the infrastructure subcategory
• The user needs help with specific Kotlin frameworks like Spring Boot or Ktor in depth -- check framework-specific skills
• The user wants general JVM tuning (heap sizing, GC selection, JFR) -- check the jvm-performance skill

---

Process

1. Determine the Kotlin Target Platform and Runtime

Before writing a single line of configuration, establish the deployment target because it determines the entire dependency graph, compiler options, and plugin set.

• JVM backend: Standard Kotlin JVM target. Confirm the JDK version (LTS: 17 or 21 preferred in 2024+). Set jvmTarget in compileKotlin to match -- mismatches between the JDK version and jvmTarget cause subtle bytecode issues.
• Kotlin/JVM with framework: Identify Spring Boot (Spring plugin + kotlin-spring plugin required for open classes), Ktor (no special compiler plugins but needs coroutines), or Quarkus (Quarkus Kotlin extension + all-open plugin for CDI).
• Kotlin Multiplatform: Identify shared vs. platform-specific source sets (commonMain, jvmMain, iosMain). This requires kotlin-multiplatform plugin and cannot coexist simply with kotlin("jvm").
• Kotlin/JS or Kotlin/Wasm: Confirm browser vs. Node.js target and IR backend requirement (legacy backend is deprecated as of Kotlin 1.9).
• Confirm the Kotlin version to use. As of 2024, Kotlin 2.0.x is stable with K2 compiler. Kotlin 1.9.x is the LTS-stable fallback. K2 brings 2x faster compilation but has different plugin compatibility requirements.

2. Choose and Configure the Build System

The build system is the backbone of the project. Kotlin DSL for Gradle is the strongly preferred choice for new Kotlin projects.

• Gradle with Kotlin DSL (build.gradle.kts): Use this for all new JVM/KMP projects. It provides IDE completion, type safety, and is the canonical Kotlin tooling path. Use Gradle 8.5+ for Kotlin 2.x support.
• Maven: Use only if your organization mandates Maven or you are integrating into an existing Maven monorepo. Maven Kotlin compilation is slower and has less community momentum. Use kotlin-maven-plugin version matching the Kotlin version exactly.
• Convention plugins (Gradle): For multimodule projects, extract shared build logic into buildSrc or gradle/libs.versions.toml + precompiled script plugins in an included build. Never duplicate build.gradle.kts logic across modules.
• Configure gradle/libs.versions.toml (Gradle version catalog) for all dependency versions. This is mandatory for teams of 3+ to prevent version drift:

  [versions]
  kotlin = "2.0.21"
  coroutines = "1.8.1"
  serialization = "1.7.3"
  ktor = "2.3.12"
  [libraries]
  kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "kotlin" }
  kotlinx-coroutines-core = { module = "org.jetbrains.coroutines:kotlinx-coroutines-core", version.ref = "coroutines" }
  

• Set the Gradle wrapper version precisely: ./gradlew wrapper --gradle-version=8.10.2 --distribution-type=bin. Commit the wrapper JAR.
• Enable Gradle build cache in gradle.properties: org.gradle.caching=true. Enable configuration cache: org.gradle.configuration-cache=true (verify plugin compatibility first).

3. Configure the Kotlin Compiler Plugin and Core Options

Compiler configuration is where most teams make critical mistakes. Get this right at day one.

• In build.gradle.kts, configure compileKotlin and compileTestKotlin tasks:

  tasks.withType<KotlinCompile>().configureEach {
      compilerOptions {
          jvmTarget.set(JvmTarget.JVM_21)
          freeCompilerArgs.addAll(
              "-Xjsr305=strict",            // Treat Spring/JSR-305 nullability annotations as strict
              "-Xemit-jvm-type-annotations", // Preserve type annotations in bytecode
              "-opt-in=kotlin.RequiresOptIn" // Enable opt-in API mechanism globally
          )
          allWarningsAsErrors.set(true)     // In new projects -- enforce from day one
          progressiveMode.set(true)         // Get deprecation warnings for upcoming Kotlin changes
      }
  }
  

• -Xjsr305=strict: Critical for Spring Boot interop. Without it, Spring's @Nullable and @NonNull annotations are ignored by the Kotlin compiler, defeating null safety.
• Explicit API mode: For library projects or shared modules, add explicitApi() to the kotlin {} block. This forces visibility modifiers on all public declarations and prevents accidental API surface exposure.
• jvmTarget alignment: If using JDK 21 but setting jvmTarget = JVM_17, ensure the Gradle java plugin also targets 17 via java { sourceCompatibility = JavaVersion.VERSION_17 }. Mismatch causes IncompatibleClassChangeError at runtime.
• K2 compiler (Kotlin 2.0+): The K2 compiler is default. Ensure all annotation processors (kapt) or KSP processors are K2-compatible. Prefer KSP over kapt for new projects -- kapt requires a separate Kotlin compilation round and is significantly slower.

4. Set Up Essential Kotlin Dependencies

Define a canonical dependency baseline for the project type.

• All JVM projects:

  dependencies {
      implementation(kotlin("stdlib"))
      // Do NOT add kotlin-stdlib-jdk8 or kotlin-stdlib-jdk7 separately for Kotlin 1.8+
      // they are merged into kotlin-stdlib
  }
  

• Coroutines (any project doing async I/O or concurrent work):

  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.1")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:1.8.1") // For JDK8 integration
  testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1")
  

• Serialization: For JSON/Protobuf without reflection overhead. Add the plugin in plugins {} block AND the runtime dependency:

  // plugins block
  kotlin("plugin.serialization") version libs.versions.kotlin.get()
  // dependencies block
  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
  

• Testing baseline: Use JUnit 5 (Jupiter) with Kotest assertions or MockK for idiomatic Kotlin testing:

  testImplementation("org.junit.jupiter:junit-jupiter:5.11.3")
  testImplementation("io.mockk:mockk:1.13.13")
  testImplementation("io.kotest:kotest-assertions-core:5.9.1")
  testRuntimeOnly("org.junit.platform:junit-platform-launcher")
  tasks.test { useJUnitPlatform() }
  

• Never mix kotlin-test and JUnit 5 test annotations in the same module -- pick one assertion style and be consistent.

5. Configure Code Quality Tooling

Quality tooling must be configured before the first commit reaches main, not retrofitted later.

• ktlint (formatting): Use the jlleitschuh/ktlint-gradle plugin or the official ktlint Gradle plugin. Configure .editorconfig at the project root:

  [*.{kt,kts}]
  ktlint_code_style = ktlint_official
  ktlint_standard_no-wildcard-imports = enabled
  max_line_length = 120
  indent_size = 4
  

  Run ./gradlew ktlintFormat as a pre-commit hook. Run ./gradlew ktlintCheck in CI (fail the build on violations).
• detekt (static analysis): Add io.gitlab.arturbosch.detekt plugin. Generate a baseline config: ./gradlew detektGenerateConfig. The default detekt.yml is a starting point -- tune it per team. Enable type resolution for stronger checks:

  detekt {
      config.setFrom("$projectDir/config/detekt/detekt.yml")
      buildUponDefaultConfig = true
      allRules = false // Only enable rules you enforce
  }
  

  Key detekt rules to enable from day one: MagicNumber, ComplexCondition, LongParameterList (threshold: 6), TooManyFunctions (threshold: 11 per class), MaxLineLength.
• Binary compatibility validator: For library/shared module projects, add org.jetbrains.kotlinx.binary-compatibility-validator. This generates a .api file tracking public API surface and fails CI when the API changes unexpectedly.
• Configure all quality checks to run in the check Gradle lifecycle task so ./gradlew check is the single CI quality gate command.

6. Establish Project Structure and Module Boundaries

Project structure communicates architectural intent and prevents coupling.

• Single-module small projects (1-5 engineers, bounded domain):

  project-root/
  ├── build.gradle.kts
  ├── settings.gradle.kts
  ├── gradle/
  │   ├── libs.versions.toml
  │   └── wrapper/
  ├── src/
  │   ├── main/kotlin/com/example/
  │   │   ├── Application.kt       # Entry point
  │   │   ├── domain/              # Business logic -- no framework deps
  │   │   ├── application/         # Use cases / services
  │   │   ├── infrastructure/      # DB, HTTP, messaging adapters
  │   │   └── api/                 # Controllers / handlers
  │   └── test/kotlin/com/example/
  └── src/integrationTest/kotlin/  # Separate source set for integration tests
  

• Multimodule projects (5+ engineers, multiple bounded contexts): Use Gradle multi-project builds with a settings.gradle.kts including all subprojects. Place shared build logic in build-logic/ as an included Gradle build with convention plugins (e.g., kotlin-library-conventions.gradle.kts, kotlin-service-conventions.gradle.kts).
• Define integration test source sets explicitly -- do not put integration tests in src/test. Create a dedicated integrationTest source set that runs against a real database or external service, separated from unit tests in CI:

  val integrationTestSourceSet = sourceSets.create("integrationTest") {
      compileClasspath += sourceSets.main.get().output + configurations.testRuntimeClasspath.get()
      runtimeClasspath += output + compileClasspath
  }
  

• Enforce module boundaries using detekt's ForbiddenImport or ArchUnit tests. Domain modules must not import infrastructure modules.

7. Configure CI/CD Integration

Kotlin's compilation speed and incremental compilation behavior require specific CI configuration.

• Gradle remote build cache: Configure Gradle Enterprise or Develocity for build cache sharing across CI agents. Without this, Kotlin compilation time on CI is 3-5x local times for large projects.
• Parallel compilation: In gradle.properties:

  org.gradle.parallel=true
  org.gradle.workers.max=4          # Set to CPU count - 1 on CI agents
  kotlin.incremental=true
  kotlin.incremental.multiplatform=true
  kotlin.daemon.jvm.options=-Xmx2g # Kotlin daemon heap -- 2GB for medium projects, 4GB for large
  org.gradle.jvmargs=-Xmx4g -XX:+UseParallelGC
  

• GitHub Actions / GitLab CI caching: Cache both the Gradle user home (~/.gradle/caches) and the project .gradle directory. Cache key must include the hash of all *.gradle.kts files and libs.versions.toml.
• Kotlin daemon on CI: Set GRADLE_OPTS=-Dkotlin.compiler.execution.strategy=in-process on CI to avoid daemon startup overhead in ephemeral build containers.
• Quality gate order in CI pipeline:
  1. ./gradlew ktlintCheck -- fast, fail early
  2. ./gradlew detekt -- static analysis
  3. ./gradlew test -- unit tests
  4. ./gradlew integrationTest -- integration tests (parallelizable)
  5. ./gradlew check -- all remaining checks including binary compatibility

8. Document Conventions and Finalize

Set the team up for long-term consistency.

• Create a CONTRIBUTING.md documenting: Kotlin version, JDK version, required Gradle wrapper version, how to run quality checks locally, branch naming, and commit message conventions.
• Create an ADR/ directory with the first Architecture Decision Record: why Kotlin was chosen, what version, and any deviations from defaults (e.g., "We disabled allWarningsAsErrors in test source sets because MockK generates some deprecation warnings we cannot control").
• Add a .kotlin-version file in the project root for tooling that reads it (some IDE plugins use it).
• Configure .gitignore with JVM/Kotlin specifics:

  .gradle/
  build/
  *.class
  *.jar
  !gradle/wrapper/gradle-wrapper.jar
  .idea/
  *.iml
  out/
  

• Pin the JDK version using a .java-version or .tool-versions (asdf) file so all developers and CI use the same JDK.

---

Output Format

When helping a user set up a Kotlin project, provide output in this structure:

## Kotlin Project Setup Plan

### Target Context
- Platform: [JVM / KMP / JS / Wasm]
- Runtime/Framework: [Spring Boot 3.x / Ktor / Quarkus / None]
- Kotlin Version: [2.0.x / 1.9.x]
- JDK Version: [21 / 17 / 11]
- Build System: [Gradle Kotlin DSL / Maven]
- Team Size: [number]
- Module Structure: [Single-module / Multi-module]

### Decision Matrix

| Concern                   | Choice                        | Rationale                                      |
|---------------------------|-------------------------------|------------------------------------------------|
| Build system              | Gradle 8.x with Kotlin DSL   | Type-safe, IDE completion, KMP-ready           |
| Dependency management     | Version catalog (libs.versions.toml) | Single source of truth for all versions  |
| Formatting                | ktlint (official style)       | Zero-config, integrates with pre-commit        |
| Static analysis           | detekt with type resolution   | Catches architecture and complexity violations |
| Async                     | kotlinx.coroutines            | Structured concurrency, cancellation support   |
| Serialization             | kotlinx.serialization         | Reflection-free, KMP-compatible                |
| Testing                   | JUnit 5 + MockK + Kotest      | Idiomatic Kotlin, coroutines test support      |
| Java interop              | -Xjsr305=strict               | Enforces nullability from Java annotations     |

### File Listing
[List every file to be created with its purpose]

### settings.gradle.kts
[Complete file content]

### build.gradle.kts (root or module)
[Complete file content]

### gradle/libs.versions.toml
[Complete file content]

### gradle.properties
[Complete file content]

### config/detekt/detekt.yml (key sections)
[Relevant configuration sections]

### .editorconfig
[Complete file content]

### src/main/kotlin/[package]/Application.kt
[Minimal entry point appropriate to the framework]

### CI Configuration (.github/workflows/ci.yml or equivalent)
[Complete CI workflow file]

### Next Steps
1. [Concrete action with command]
2. [Concrete action with command]
3. [Concrete action with command]

---

Rules

1. NEVER mix kotlin-stdlib-jdk7 or kotlin-stdlib-jdk8 as explicit dependencies for Kotlin 1.8+. These artifacts were merged into kotlin-stdlib in Kotlin 1.8. Adding them explicitly causes duplicate class warnings and can cause subtle class loading issues at runtime.

2. ALWAYS align jvmTarget in KotlinCompile tasks with the sourceCompatibility and targetCompatibility in the java plugin. If they differ by even one version, Gradle may compile Java sources to a higher bytecode version than Kotlin sources, causing UnsupportedClassVersionError in production.

3. NEVER use kapt for new projects that can use KSP. kapt runs a separate compilation round, doubling compile time for annotation-heavy projects. Dagger, Room, Moshi, and most modern processors have KSP support. The annotation processor support for kapt is being formally deprecated.

4. ALWAYS pin the Kotlin Gradle Plugin version identical to the kotlin-stdlib version. Mismatching plugin and stdlib versions is a top-3 cause of cryptic NoClassDefFoundError and AbstractMethodError at compile time.

5. NEVER enable allWarningsAsErrors = true on test source sets without accounting for third-party generated code. MockK and similar libraries generate code with deprecation warnings in recent Kotlin versions. Apply the compiler options selectively: tasks.withType<KotlinCompile>().matching { it.name.startsWith("compileMain") }.

6. ALWAYS use configureEach instead of withType<Task>.configure {} for Kotlin compile task configuration in Gradle. configureEach is lazy and avoids realizing tasks eagerly, which degrades configuration time for large multimodule builds (100+ modules can see 30-60 second overhead from eager task realization).

7. NEVER commit gradle-wrapper.jar to .gitignore. The wrapper JAR is intentionally committed to the repository. Its SHA is verified by Gradle's built-in wrapper validation. Excluding it forces every developer to run gradle wrapper before building.

8. ALWAYS configure the Kotlin daemon heap separately from the Gradle daemon heap. org.gradle.jvmargs controls the Gradle daemon. kotlin.daemon.jvm.options controls the Kotlin compiler daemon. For projects with more than 100K lines of Kotlin, the Kotlin daemon needs at least 2GB (-Xmx2g) to avoid GC-induced compilation slowdowns.

9. NEVER use wildcard imports in Kotlin source files in a team setting. Configure ktlint's no-wildcard-imports rule and detekt's NoWildcardImports rule together. Wildcard imports cause merge conflicts when multiple engineers add imports in the same file and make it impossible to grep for specific class usage.

10. ALWAYS create a dedicated integrationTest Gradle source set rather than placing integration tests in src/test. Integration tests that start Docker containers (via Testcontainers), make real HTTP calls, or write to real databases must not run with unit tests. Mixing them causes flakey unit test suites and makes fast local feedback loops impossible.

---

Edge Cases

Kotlin 2.0 K2 Compiler Plugin Incompatibility

If any annotation processor or compiler plugin in the dependency list does not support K2 (check the plugin's changelog for "K2 support" or "Kotlin 2.0 compatible"), the build will fail with This version of the kotlin-plugin requires the K2 compiler or produce incorrect output silently. Handling: Add kotlin.experimental.tryK2=true to gradle.properties first and run ./gradlew build --info to check plugin compatibility before fully committing to Kotlin 2.0. If a plugin is incompatible, either: (a) find the K2-compatible version, (b) temporarily disable that specific plugin's compilation integration, or (c) stay on Kotlin 1.9.x until the plugin is updated. For kapt specifically, K2 kapt is available as kotlin.kapt.use.k2=true but is still experimental -- prefer migrating to KSP instead.

Java/Kotlin Mixed Source Project Migration

When converting an existing Java project to Kotlin incrementally, the java and kotlin source directories must coexist. Handling: Add kotlin("jvm") plugin alongside any existing java plugin. Configure sourceSets.main.kotlin.srcDirs to include both src/main/kotlin and src/main/java if you want Kotlin to process Java sources for type resolution. Use @JvmStatic on companion object methods called from Java, @JvmOverloads for Kotlin default parameter functions called from Java, and @JvmField for constants. Critical: Kotlin sees Java nullability through @Nullable/@NonNull annotations (hence the importance of -Xjsr305=strict). Platform types (types from Java without annotations) are T! in Kotlin -- treat every platform type as potentially null until the Java code is annotated.

Gradle Configuration Cache Incompatibility with Specific Plugins

Configuration cache (org.gradle.configuration-cache=true) breaks plugins that use Project instance at execution time, access task outputs during configuration, or use deprecated APIs. When enabling it, run ./gradlew --configuration-cache build and check for configuration cache problems in the output. Handling: Common offenders are older versions of the Docker plugin, some code generation plugins, and custom buildSrc code that holds task references. Fix by: upgrading the plugin to a CC-compatible version, using @Internal task property annotations correctly, or adding the plugin to a configuration cache exclusion list as a temporary measure. Do not disable configuration cache globally for one non-compliant plugin -- isolate the non-compliant task and run it separately.

Multimodule Build with Shared Kotlin Version

In a multimodule project where some modules are libraries used by other modules, the Kotlin stdlib version must be consistent across all modules. Handling: Define the Kotlin version exclusively in the root libs.versions.toml and apply the Kotlin plugin via a convention plugin in build-logic. Never hardcode the Kotlin version string in a module's build.gradle.kts. Use kotlin("stdlib") without a version when the BOM or version catalog manages the version. Apply platform(kotlin("bom")) in projects where the Kotlin version must be enforced transitively:

implementation(platform("org.jetbrains.kotlin:kotlin-bom:${libs.versions.kotlin.get()}"))

Coroutines and suspend Functions in Spring Boot or JPA Context

When using coroutines with Spring Boot, Spring's transaction management and security context propagation do not work with suspend functions by default. Handling: Use kotlinx-coroutines-reactor for Spring WebFlux integration. For Spring MVC (blocking), use runBlocking {} only at the outermost controller layer, never inside service or repository layers. For Spring Security context in coroutines, use SecurityContext with ReactorContextWebFilter. For Spring Data JPA with coroutines, repositories must use @Transactional with a coroutine-aware transaction manager -- do not call suspend JPA operations from a coroutine that doesn't have a Dispatchers.IO context, as JPA blocks threads.

Deterministic Snapshot/Version Handling in CI

Kotlin snapshot versions (2.1.0-SNAPSHOT) are sometimes referenced in tutorials and documentation. Handling: Never use snapshot versions in production projects. Snapshots are published to the Kotlin bootstrap Maven repository, not Maven Central, and can change without notice, causing irreproducible builds. If you need a pre-release, use the RC or beta releases from Maven Central (e.g., 2.1.0-RC). If a team member's ~/.gradle/caches has a snapshot cached, it may differ from a fresh CI environment, causing "works on my machine" failures. Enforce --refresh-dependencies in CI for any snapshot dependency if one accidentally slips through.

OptIn and Experimental API Management

Kotlin's experimental/opt-in API system (formerly @Experimental) is commonly misunderstood. Using any kotlinx.coroutines experimental API, Flow operators marked @FlowPreview, or custom @RequiresOptIn annotations without proper opt-in causes compile errors. Handling: Use @OptIn(ExperimentalCoroutinesApi::class) at the call site for specific functions. For project-wide opt-in (e.g., you're using many coroutines experimental APIs), add to compiler args: -opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi. For your own library code, mark experimental APIs with @RequiresOptIn(level = RequiresOptIn.Level.ERROR) to force callers to explicitly acknowledge the instability. Never add a blanket -opt-in=kotlin.RequiresOptIn that suppresses all opt-in requirements without per-API review.

Windows Build Environment

Kotlin/Gradle builds on Windows have known friction points. Handling: Use WSL2 for development whenever possible -- Gradle's file system watching and incremental compilation work significantly better on Linux (EXT4) than Windows NTFS. If native Windows is required: set GRADLE_USER_HOME to a short path (e.g., C:\gradle) to avoid Windows MAX_PATH (260 characters) issues with deeply nested Gradle cache directories. Enable long path support via Group Policy or git config core.longpaths true. Configure antivirus exclusions for the Gradle cache and build directories -- real-time AV scanning of .class files during compilation is a major performance killer (can increase build times by 40-100%).

---

Example

Input: "I need to set up a new Kotlin project for a REST API service using Ktor. It's a team of 4 engineers. We're targeting JDK 21, want production-ready quality gates, and will deploy to Kubernetes. This is a greenfield project."

Output:

Kotlin Project Setup Plan

Target Context

• Platform: JVM
• Runtime/Framework: Ktor 2.3.x (coroutines-native, no Spring)
• Kotlin Version: 2.0.21
• JDK Version: 21
• Build System: Gradle 8.10.x with Kotlin DSL
• Team Size: 4
• Module Structure: Single-module (with dedicated integrationTest source set)

Decision Matrix

File Listing

• settings.gradle.kts -- project name and plugin management
• build.gradle.kts -- all build configuration
• gradle/libs.versions.toml -- all version pinning
• gradle.properties -- JVM args, feature flags
• config/detekt/detekt.yml -- static analysis rules
• .editorconfig -- formatting rules
• src/main/kotlin/com/example/api/Application.kt -- Ktor entry point
• src/main/kotlin/com/example/api/plugins/Routing.kt -- route configuration
• src/main/kotlin/com/example/api/plugins/Serialization.kt -- content negotiation
• src/test/kotlin/com/example/api/ApplicationTest.kt -- unit test example
• .github/workflows/ci.yml -- GitHub Actions CI pipeline
• Dockerfile -- multi-stage Ktor container
• .gitignore -- JVM/Gradle/Kotlin specific ignores
• CONTRIBUTING.md -- team conventions

---

settings.gradle.kts

rootProject.name = "ktor-api-service"

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
    }
    versionCatalogs {
        create("libs") {
            from(files("gradle/libs.versions.toml"))
        }
    }
}

---

gradle/libs.versions.toml

[versions]
kotlin = "2.0.21"
ktor = "2.3.12"
coroutines = "1.8.1"
serialization = "1.7.3"
logback = "1.5.8"
junit5 = "5.11.3"
mockk = "1.13.13"
kotest = "5.9.1"
detekt = "1.23.7"
ktlint-plugin = "12.1.1"
shadow = "8.1.1"

[libraries]
ktor-server-core = { module = "io.ktor:ktor-server-core-jvm", version.ref = "ktor" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty-jvm", version.ref = "ktor" }
ktor-server-content-negotiation = { module = "io.ktor:ktor-server-content-negotiation-jvm", version.ref = "ktor" }
ktor-server-status-pages = { module = "io.ktor:ktor-server-status-pages-jvm", version.ref = "ktor" }
ktor-server-call-logging = { module = "io.ktor:ktor-server-call-logging-jvm", version.ref = "ktor" }
ktor-server-metrics-micrometer = { module = "io.ktor:ktor-server-metrics-micrometer-jvm", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json-jvm", version.ref = "ktor" }
kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
kotlinx-serialization-json = { module = "org.jetbrains.kotlinx:kotlinx-serialization-json", version.ref = "serialization" }
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
junit5-api = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit5" }
junit5-engine = { module = "org.junit.jupiter:junit-jupiter-engine", version.ref = "junit5" }
junit5-launcher = { module = "org.junit.platform:junit-platform-launcher" }
mockk = { module = "io.mockk:mockk", version.ref = "mockk" }
kotest-assertions = { module = "io.kotest:kotest-assertions-core", version.ref = "kotest" }
ktor-server-tests = { module = "io.ktor:ktor-server-tests-jvm", version.ref = "ktor" }
kotlinx-coroutines-test = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-test", version.ref = "coroutines" }

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
detekt = { id = "io.gitlab.arturbosch.detekt", version.ref = "detekt" }
ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint-plugin" }
shadow = { id = "com.github.johnrengelman.shadow", version.ref = "shadow" }

---

build.gradle.kts

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
    alias(libs.plugins.kotlin.jvm)
    alias(libs.plugins.kotlin.serialization)
    alias(libs.plugins.detekt)
    alias(libs.plugins.ktlint)
    alias(libs.plugins.shadow)
    application
}

group = "com.example.api"
version = "0.1.0-SNAPSHOT"

application {
    mainClass.set("com.example.api.ApplicationKt")
    // Required for Netty + JDK 21 virtual threads if enabled
    applicationDefaultJvmArgs = listOf("-Dio.ktor.development=${extra["development"] ?: "false"}")
}

// ──────────────────────────────────────────────
// Integration test source set
// ──────────────────────────────────────────────
val integrationTestSourceSet = sourceSets.create("integrationTest") {
    compileClasspath += sourceSets.main.get().output + configurations.testRuntimeClasspath.get()
    runtimeClasspath += output + compileClasspath
}

val integrationTestImplementation: Configuration by configurations.getting {
    extendsFrom(configurations.testImplementation.get())
}

val integrationTest by tasks.registering(Test::class) {
    testClassesDirs = integrationTestSourceSet.output.classesDirs
    classpath = integrationTestSourceSet.runtimeClasspath
    shouldRunAfter(tasks.test)
    useJUnitPlatform()
}

tasks.check { dependsOn(integrationTest) }

// ──────────────────────────────────────────────
// Kotlin compiler configuration
// ──────────────────────────────────────────────
tasks.withType<KotlinCompile>().configureEach {
    compilerOptions {
        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_21)
        freeCompilerArgs.addAll(
            "-Xjsr305=strict",
            "-opt-in=kotlin.RequiresOptIn",
            "-opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi"
        )
        progressiveMode.set(true)
    }
}

// Apply allWarningsAsErrors only to main sources, not test sources
// (MockK and Ktor test APIs have some deprecation warnings in Kotlin 2.x)
tasks.named<KotlinCompile>("compileKotlin") {
    compilerOptions {
        allWarningsAsErrors.set(true)
    }
}

// ──────────────────────────────────────────────
// Java version alignment
// ──────────────────────────────────────────────
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(21))
    }
}

// ──────────────────────────────────────────────
// Dependencies
// ──────────────────────────────────────────────
dependencies {
    implementation(libs.ktor.server.core)
    implementation(libs.ktor.server.netty)
    implementation(libs.ktor.server.content.negotiation)
    implementation(libs.ktor.server.status.pages)
    implementation(libs.ktor.server.call.logging)
    implementation(libs.ktor.server.metrics.micrometer)
    implementation(libs.ktor.serialization.kotlinx.json)
    implementation(libs.kotlinx.coroutines.core)
    implementation(libs.kotlinx.serialization.json)
    implementation(libs.logback.classic)

    testImplementation(libs.junit5.api)
    testRuntimeOnly(libs.junit5.engine)
    testRuntimeOnly(libs.junit5.launcher)
    testImplementation(libs.mockk)
    testImplementation(libs.kotest.assertions)
    testImplementation(libs.ktor.server.tests)
    testImplementation(libs.kotlinx.coroutines.test)
}

// ──────────────────────────────────────────────
// Test configuration
// ──────────────────────────────────────────────
tasks.test {
    useJUnitPlatform()
    maxHeapSize = "512m"
    jvmArgs("-XX:+UseZGC") // ZGC for low-latency test execution on JDK 21
    testLogging {
        events("passed", "skipped", "failed")
        exceptionFormat = org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
    }
}

// ──────────────────────────────────────────────
// detekt configuration
// ──────────────────────────────────────────────
detekt {
    config.setFrom("$projectDir/config/detekt/detekt.yml")
    buildUponDefaultConfig = true
    source.setFrom(
        "src/main/kotlin",
        "src/test/kotlin",
        "src/integrationTest/kotlin"
    )
}

// ──────────────────────────────────────────────
// ktlint configuration
// ──────────────────────────────────────────────
ktlint {
    version.set("1.3.1")
    android.set(false)
    reporters {
        reporter(org.jlleitschuh.gradle.ktlint.reporter.ReporterType.SARIF)
        reporter(org.jlleitschuh.gradle.ktlint.reporter.ReporterType.PLAIN)
    }
}

// ──────────────────────────────────────────────
// Shadow JAR (fat JAR for Kubernetes deployment)
// ──────────────────────────────────────────────
tasks.shadowJar {
    archiveClassifier.set("")
    manifest {
        attributes(mapOf("Main-Class" to application.mainClass.get()))
    }
    mergeServiceFiles() // Required for Netty SPI files
}

---

gradle.properties

# Kotlin/Gradle daemon memory
org.gradle.jvmargs=-Xmx2g -XX:+UseParallelGC -XX:MaxMetaspaceSize=512m
kotlin.daemon.jvm.options=-Xmx2g

# Performance
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.configuration-cache.problems=warn

# Kotlin
kotlin.incremental=true
kotlin.incremental.multiplatform=false
kotlin.stdlib.default.dependency=true

# Ktor development mode (override with -Pdevelopment=true locally)
development=false

# Suppress Gradle version warnings
org.gradle.warning.mode=all

---

src/main/kotlin/com/example/api/Application.kt

package com.example.api

import com.example.api.plugins.configureRouting
import com.example.api.plugins.configureSerialization
import com.example.api.plugins.configureStatusPages
import io.ktor.server.application.Application
import io.ktor.server.netty.EngineMain

fun main(args: Array<String>): Unit = EngineMain.main(args)

// Public for testApplication {} to use
fun Application.module() {
    configureSerialization()
    configureStatusPages()
    configureRouting()
}

---

src/main/kotlin/com/example/api/plugins/Serialization.kt

package com.example.api.plugins

import io.ktor.serialization.kotlinx.json.json
import io.ktor.server.application.Application
import io.ktor.server.application.install
import io.ktor.server.plugins.contentnegotiation.ContentNegotiation
import kotlinx.serialization.json.Json

fun Application.configureSerialization() {
    install(ContentNegotiation) {
        json(Json {
            prettyPrint = false       // Never pretty-print in production -- wastes bytes
            isLenient = false         // Strict parsing -- reject malformed JSON
            ignoreUnknownKeys = true  // Forward compatibility for API evolution
            encodeDefaults = true     // Include default values in serialized output
        })
    }
}

---

src/test/kotlin/com/example/api/ApplicationTest.kt

package com.example.api

import io.kotest.matchers.shouldBe
import io.ktor.client.request.get
import io.ktor.http.HttpStatusCode
import io.ktor.server.testing.testApplication
import org.junit.jupiter.api.Test

class ApplicationTest {

    @Test
    fun `health endpoint returns 200 OK`() = testApplication {
        application { module() }
        val response = client.get("/health")
        response.status shouldBe HttpStatusCode.OK
    }
}

---

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 20

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
          cache: gradle

      - name: Cache Gradle dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle.kts', '**/libs.versions.toml') }}
          restore-keys: |
            ${{ runner.os }}-gradle-

      - name: Validate Gradle wrapper
        uses: gradle/actions/wrapper-validation@v3

      - name: Check formatting (ktlint)
        run: ./gradlew ktlintCheck --no-daemon

      - name: Static analysis (detekt)
        run: ./gradlew detekt --no-daemon

      - name: Unit tests
        run: ./gradlew test --no-daemon
        env:
          GRADLE_OPTS: -Dkotlin.compiler.execution.strategy=in-process

      - name: Integration tests
        run: ./gradlew integrationTest --no-daemon

      - name: Build shadow JAR
        run: ./gradlew shadowJar --no-daemon

      - name: Upload test results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: test-results
          path: build/reports/tests/

---

Dockerfile

# Stage 1: Build
FROM eclipse-temurin:21-jdk-alpine AS builder
WORKDIR /build
COPY gradle/ gradle/
COPY gradlew settings.gradle.kts build.gradle.kts gradle.properties ./
# Cache dependency download layer separately from source compilation
RUN ./gradlew dependencies --no-daemon --quiet
COPY src/ src/
RUN ./gradlew shadowJar --no-daemon --no-build-cache

# Stage 2: Runtime
FROM eclipse-temurin:21-jre-alpine AS runtime
# Run as non-root for Kubernetes security policies
RUN addgroup -S ktor && adduser -S ktor -G ktor
WORKDIR /app
COPY --from=builder /build/build/libs/*.jar app.jar
USER ktor
EXPOSE 8080
ENTRYPOINT ["java", \
  "-XX:+UseZGC", \
  "-XX:MaxRAMPercentage=75.0", \
  "-Djava.security.egd=file:/dev/./urandom", \
  "-jar", "app.jar"]

---

Next Steps

1. Initialize the Gradle wrapper:

   gradle wrapper --gradle-version=8.10.2 --distribution-type=bin
   

2. Generate the detekt baseline config:

   ./gradlew detektGenerateConfig
   # Then review and tune config/detekt/detekt.yml
   

3. Install the pre-commit hook for ktlint:

   ./gradlew addKtlintCheckGitPreCommitHook
   

4. Verify the full quality gate passes before the first feature commit:

   ./gradlew check
   

5. Create the first ADR in docs/adr/0001-kotlin-ktor-project-setup.md documenting why Ktor was chosen over Spring Boot, the Kotlin version decision, and any non-default compiler flags with their rationale.

6. Configure branch protection on main to require all CI checks passing before merge, and set the CI workflow as a required status check.