Suggestion: Promote Gradle Version Catalogs in Ktor Documentation and Project Generator #5261
Description
Summary
I suggest that Ktor officially promote and document the use of Gradle Version Catalogs (libs.versions.toml) in the next version release, including:
- Adding version catalog support to the Ktor Project Generator (start.ktor.io)
- Updating official documentation with version catalog examples
- Providing migration guides for existing projects
Motivation
Current State:
- Ktor internally uses version catalogs (as seen in the main repository)
- The Ktor Project Generator (start.ktor.io) still generates projects with traditional dependency management
- Official documentation examples primarily show traditional
build.gradle.ktsdependency declarations
Why Version Catalogs Matter:
1. Centralized Dependency Management
- Single source of truth for all dependency versions
- Easier to maintain and update dependencies across multi-module projects
- Reduces version conflicts and inconsistencies
2. Type-Safe Dependency References
- IDE autocomplete support for dependencies
- Compile-time verification of dependency references
- Reduces typos and errors in dependency declarations
3. Better Developer Experience
- Clear separation between version management and build logic
- Easier onboarding for new team members
- Consistent with modern Gradle best practices
4. Industry Standard
- Gradle officially recommends version catalogs (stable since Gradle 7.0)
- Widely adopted by the Kotlin/Android community
- Aligns with Kotlin Multiplatform best practices
- Many modern Kotlin projects have already adopted this approach
Proposed Changes
1. Ktor Project Generator (start.ktor.io)
Add an option or make it default to generate projects with version catalogs:
Current generated structure:
my-ktor-app/
├── build.gradle.kts
├── settings.gradle.kts
└── src/
Proposed structure:
my-ktor-app/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle/
│ └── libs.versions.toml
└── src/
Example gradle/libs.versions.toml:
[versions]
kotlin = "2.3.0"
ktor = "3.3.2"
logback = "1.5.13"
[libraries]
ktor-server-core = { module = "io.ktor:ktor-server-core" }
ktor-server-netty = { module = "io.ktor:ktor-server-netty" }
ktor-server-content-negotiation = { module = "io.ktor:ktor-server-content-negotiation" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json" }
logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
ktor = { id = "io.ktor.plugin", version.ref = "ktor" }
kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }Example build.gradle.kts:
plugins {
alias(libs.plugins.kotlin.jvm)
alias(libs.plugins.ktor)
alias(libs.plugins.kotlin.serialization)
}
dependencies {
implementation(libs.ktor.server.core)
implementation(libs.ktor.server.netty)
implementation(libs.ktor.server.content.negotiation)
implementation(libs.ktor.serialization.kotlinx.json)
implementation(libs.logback.classic)
}2. Documentation Updates
- Update all code examples in the official documentation to show version catalog usage
- Add a dedicated page explaining version catalogs for Ktor projects
- Include migration guide from traditional dependency management
- Add best practices section for managing Ktor dependencies
3. Sample Projects
- Update ktor-samples repository to use version catalogs
- Provide template repositories with version catalogs pre-configured
Benefits for Ktor Users
- Consistency: Aligns with how Ktor itself manages dependencies internally
- Scalability: Easier to manage dependencies in multi-module Ktor projects
- Maintainability: Simpler dependency updates and version management
- Modern Practices: Follows current Gradle and Kotlin ecosystem standards
- Better Tooling: Improved IDE support and autocomplete
- Reduced Errors: Type-safe dependency references prevent common mistakes
- Team Collaboration: Easier for teams to maintain consistent dependency versions
Implementation Considerations
- Backward Compatibility: Keep supporting traditional dependency management
- Migration Path: Provide clear migration guides for existing projects
- Documentation: Comprehensive examples for both approaches
- Generator Options: Allow users to choose between traditional and version catalog approaches (similar to how other options are presented)
- Default Recommendation: Consider making version catalogs the default for new projects
Community Adoption
Version catalogs have been widely adopted across the Kotlin ecosystem:
- Android projects commonly use version catalogs
- Kotlin Multiplatform projects benefit from centralized dependency management
- Many popular Kotlin libraries and frameworks have adopted this approach
- Gradle has made this a stable feature and actively promotes its use
References
- Gradle Version Catalogs Documentation
- Kotlin Multiplatform Version Catalogs Guide
- Ktor's own usage: ktorio/ktor/gradle/libs.versions.toml
Conclusion
Adopting and promoting Gradle Version Catalogs would:
- Modernize Ktor project templates
- Improve developer experience for both new and experienced users
- Align with industry best practices
- Make Ktor projects more maintainable and scalable
- Demonstrate Ktor's commitment to modern development practices
I believe this would be a valuable addition to the next Ktor release and would benefit the entire Ktor community by providing a better starting point for new projects and a clear upgrade path for existing ones.