Kotlin App Template

Overview

A GitHub template for bootstrapping Kotlin projects with static analysis, testing, and continuous integration preconfigured and ready to go. Use this template to create a new Kotlin/JVM project and be up and running in seconds.

Features 🦄

• 100% Kotlin-only template.
• Kotlin 2.4 with K2 Compiler.
• JVM 17+ target.
• 100% Gradle Kotlin DSL setup (Gradle 9.5).
• CI setup with GitHub Actions (builds on JDK 17 and 21).
• Aggressive Kotlin static analysis via detekt, ktlint, diktat, and spotless.
• Test suite with JUnit 5, AssertJ, MockK, Mockito, and Turbine.
• Code coverage via Jacoco and Kover (≥ 80% enforced).
• Mutation testing via Pitest.
• API documentation via Dokka.
• Pre-commit Git hooks for automated quality checks.
• Project rename script for quick customization.
• GitHub Issues templates (bug report + feature request).

Requirements

Tool	Version
JDK	17+
Gradle	9.5 (included via wrapper)

No additional installation is required — the Gradle wrapper (./gradlew) is included in the repository.

Getting Started

1. Create a new repository from this template

Click "Use this template" on GitHub, or clone the repository directly:

git clone https://github.com/ashtanko/kotlin-app-template.git
cd kotlin-app-template

2. Rename the project (optional)

A rename script is provided to update the project name, package, and GitHub owner in one step:

./scripts/rename-project.sh -n "my-project" -p "com.example.myproject"

Run with --help for all available options, or --dry-run to preview changes.

3. Build the project

./gradlew build

4. Run the application

./gradlew run

Note: The default main class is link.kotlin.scripts.Application (configured in build.gradle.kts). Update this to your own entry point after scaffolding.

Scripts & Commands

Makefile Shortcuts

Command	Description
make check	Run all static analysis (spotless, detekt, ktlint, diktat)
make test	Run the test suite
make report	Generate Jacoco coverage report
make kover	Generate Kover HTML coverage report
make detekt	Run Detekt analysis only
make diktat	Run Diktat check only
make md	Regenerate README.md from config/main.md + detekt report + license
make all	Run checks, build, and regenerate README
make lines	Count lines of Kotlin code
make bump-gradle	Upgrade the Gradle wrapper version

Gradle Tasks

Command	Description
./gradlew build	Compile and run tests
./gradlew test	Run the test suite
./gradlew run	Run the application
./gradlew detekt	Run Detekt static analysis
./gradlew ktlintCheck	Check code style with ktlint
./gradlew diktatCheck	Check code style with Diktat
./gradlew spotlessApply	Auto-format code and apply license headers
./gradlew jacocoTestReport	Generate Jacoco coverage report
./gradlew koverHtmlReport	Generate Kover HTML coverage report
./gradlew koverXmlReport	Generate Kover XML coverage report
./gradlew dokkaHtml	Generate HTML API documentation
./gradlew pitest	Run mutation tests

Environment Variables

Variable	Description	Default
PITEST_THREADS	Number of threads for mutation tests	Half of available CPU cores

Testing

Tests are located in src/test/kotlin/ and use:

• JUnit 5 — test runner and parameterized tests
• AssertJ — fluent assertions
• MockK — Kotlin-idiomatic mocking
• Mockito — additional mocking support
• Turbine — Kotlin Flow testing

Run all tests:

./gradlew test
# or
make test

Generate coverage reports:

./gradlew jacocoTestReport   # Jacoco (HTML + XML + CSV)
./gradlew koverHtmlReport    # Kover

Run mutation testing:

./gradlew pitest

Coverage is enforced at ≥ 80% via Kover and ≥ 50% via Jacoco verification.

Project Structure

kotlin-app-template/
├── build.gradle.kts                # Main Gradle build configuration
├── settings.gradle.kts             # Gradle settings (project name, toolchain resolver)
├── gradle.properties               # Gradle and Kotlin build properties
├── gradle/
│   └── libs.versions.toml          # Centralized dependency and version catalog
├── Makefile                        # Task automation shortcuts
├── config/
│   ├── main.md                     # Source for the main README section
│   ├── license.md                  # License section appended to README
│   └── detekt/
│       ├── detekt.yml              # Detekt rule configuration
│       └── detekt-baseline.xml     # Detekt baseline for existing issues
├── spotless/
│   └── copyright.kt               # License header template for Spotless
├── scripts/
│   ├── git-hooks/
│   │   └── pre-commit.sh           # Pre-commit hook (static analysis)
│   └── rename-project.sh           # Project rename utility
├── src/
│   ├── main/kotlin/dev/shtanko/template/
│   │   ├── Calculator.kt           # Example calculator class
│   │   ├── DataProcessor.kt        # Example data processor with coroutines/Flow
│   │   └── DivideByZeroException.kt
│   └── test/kotlin/dev/shtanko/template/
│       ├── ExampleTest.kt           # Example calculator tests
│       └── DataProcessorTest.kt     # Data processor tests
├── .github/
│   └── workflows/
│       └── ci.yml                   # GitHub Actions CI pipeline
├── codecov.yml                      # Codecov configuration
├── renovate.json                    # Renovate bot configuration for dependency updates
├── diktat-analysis.yml              # Diktat analysis configuration
├── checksum.sh                      # Checksum verification script
└── AGENTS.md                        # AI agent guidelines

CI/CD

The project includes a GitHub Actions workflow (.github/workflows/ci.yml) that runs on every push to main and on pull requests:

1. Build & Test — compiles and runs tests on JDK 17 and JDK 21.
2. Static Analysis — runs detekt, ktlint, and diktat.
3. Coverage Reporting — generates Jacoco and Kover reports, uploads to Codecov and Codacy.
4. Code Quality — runs Codacy Analysis CLI.

Contributing 🤝

Feel free to open an issue or submit a pull request for any bugs/improvements.

Use Conventional Commits for PR titles:

<type>(<scope>): <short description>

Types: feat, fix, chore, docs, test, refactor.

detekt

Metrics

• 10 number of properties

• 21 number of functions

• 5 number of classes

• 1 number of packages

• 5 number of kt files

Complexity Report

• 364 lines of code (loc)

• 183 source lines of code (sloc)

• 117 logical lines of code (lloc)

• 137 comment lines of code (cloc)

• 23 cyclomatic complexity (mcc)

• 4 cognitive complexity

• 0 number of total code smells

• 74% comment source ratio

• 196 mcc per 1,000 lloc

• 0 code smells per 1,000 lloc

Findings (0)

generated with detekt version 1.23.8 on 2026-05-11 11:58:41 UTC

License

Designed and developed by 2024 ashtanko (Oleksii Shtanko)

  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.