Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Guides expert-level kotlin project setup implementation: kotlin and best-practices decision frameworks, production-ready patterns, and concrete templates for kotlin project setup workflows.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
848 lines · 4,791 words
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
Guides expert-level kotlin project setup implementation: kotlin and best-practices decision frameworks, production-ready patterns, and concrete templates for kotlin project setup workflows.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Kotlin Project Setup skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
When to Use
Process
Output Format
Rules
Edge Cases
Example
Kotlin Project Setup Plan
@JvmStatic, @JvmOverloads, and incremental migration strategyThe 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
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.
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).
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.
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.
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 = 4Run ./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.
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 testsMultimodule 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.
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:+UseParallelGCGitHub 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:
./gradlew ktlintCheck -- fast, fail early
./gradlew detekt -- static analysis
./gradlew test -- unit tests
./gradlew integrationTest -- integration tests (parallelizable)
./gradlew check -- all remaining checks including binary compatibility
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.
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]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.
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.
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.
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.
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") }.
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).
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.
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.
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.
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.
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.
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.
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.
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()}"))suspend Functions in Spring Boot or JPA ContextWhen 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.
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 ManagementKotlin'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.
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%).
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:
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)
| Concern | Choice | Rationale |
|---|---|---|
| Build system | Gradle 8.10 with Kotlin DSL | Type-safe config, Kotlin 2.0 support, KSP-ready |
| Dependency versions | libs.versions.toml version catalog | Single source of truth, IDE completion |
| Formatting | ktlint 1.3.x (official style) | Automated, pre-commit enforced |
| Static analysis | detekt 1.23.x with type resolution | Complexity/coupling detection |
| HTTP framework | Ktor 2.3.x | Lightweight, coroutines-native, minimal reflection |
| Async | kotlinx.coroutines 1.8.1 | Structured concurrency, Ktor native |
| Serialization | kotlinx.serialization JSON | Reflection-free, Ktor Content Negotiation |
| Testing | JUnit 5 + MockK + Kotest + Ktor testApplication | Idiomatic Kotlin, suspend-function testing |
| Java nullability | -Xjsr305=strict | Future-proofs any Java interop |
| Containerization | Ktor shadowJar plugin + multi-stage Dockerfile | Minimal image, fat JAR for K8s |
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.ktsrootProject.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.ktsimport 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=allsrc/main/kotlin/com/example/api/Application.ktpackage 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.ktpackage 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.ktpackage 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.ymlname: 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"]Initialize the Gradle wrapper:
gradle wrapper --gradle-version=8.10.2 --distribution-type=binGenerate the detekt baseline config:
./gradlew detektGenerateConfig
# Then review and tune config/detekt/detekt.ymlInstall the pre-commit hook for ktlint:
./gradlew addKtlintCheckGitPreCommitHookVerify the full quality gate passes before the first feature commit:
./gradlew checkCreate 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.
Configure branch protection on main to require all CI checks passing before merge, and set the CI workflow as a required status check.
SKILL.md
848 lines · 4,791 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Kotlin Project Setup bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for