Kotlin Multiplatform KMP-Template

A modern, production-ready template for building Kotlin Multiplatform (KMP) applications with native UI targeting Android and iOS. This template provides a solid foundation for creating cross-platform apps using Compose Multiplatform and SwiftUI for the UI layer and Kotlin Multiplatform for the shared logic.

🚀 Features

• Kotlin Multiplatform with Kotlin 2.2.21
• Compose Multiplatform for Android UI
• SwiftUI for iOS UI
• Decompose for navigation and component lifecycle management
• MVVM + MVI architecture with MVIKotlin
• Dependency Injection with Koin
• Networking with Ktor
• Testing with Kotest
• Logging with Kermit
• Feature Flags with ConfigCat and Firebase Remote Config
• Database with Supabase
• Modern Android (API 26+, Compile SDK 36)

📱 Supported Platforms

• Android: API 26+ (Android 8.0+)
• iOS: iOS 18.2+
• Shared: Common Kotlin code

🛠️ Getting Started

Prerequisites

• Android Studio Hedgehog (2023.1.1) or later
• Xcode 16.0 or later (for iOS development)
• Kotlin 2.2.21 or later
• Java 17 or later
• Gradle 8.0 or later

Quick Start

1. Clone the repository

   git clone <your-repo-url>
   cd KMP-Template

2. Open in Android Studio

   • Open the project in Android Studio
   • Sync Gradle files
   • Wait for the initial build to complete

3. Run on Android

   • Select an Android device or emulator
   • Click the "Run" button or press Shift + F10

4. Run on iOS

   • Open iosApp/KMP-Template.xcodeproj in Xcode
   • Select an iOS simulator or device
   • Press Cmd + R to build and run

5. Set up GitHub Actions (Optional)

   • Configure required secrets in your repository settings
   • Customize workflow variables for your project
   • See GitHub Actions Workflows for detailed setup

6. Configure MCP Servers (Optional)

   • Set up environment variables for API keys
   • Configure GitHub and Context7 MCP servers
   • See MCP Servers Configuration for setup instructions

Customization

1. Update package names

   • Replace com.adriandeleon.template with your package name
   • Update in composeApp/build.gradle.kts
   • Update in shared/build.gradle.kts
   • Update in iosApp/KMP-Template/Info.plist

2. Update app name

   • Android: Update app_name in composeApp/src/androidMain/res/values/strings.xml
   • iOS: Update CFBundleDisplayName in iosApp/KMP-Template/Info.plist

3. Update bundle identifier

   • iOS: Update CFBundleIdentifier in iosApp/KMP-Template/Info.plist

📚 Project Documentation

• GitHub Actions Workflows - Configurable CI/CD workflows
• MCP Servers Configuration - AI assistance setup and configuration
• Pre-Commit Hooks - Local code quality automation
• Kotlin Format & Lint - Kotlin code quality tools
• Swift Format & Lint - Swift code quality tools
• Pull Request Checks - Automated PR validation
• Unit Tests Shared - Testing strategies and tools
• Code Coverage Reports - Coverage configuration and reporting
• Feature Flags Integration - Feature toggles and configuration management
• Supabase Integration - Backend-as-a-Service setup
• Firebase Integration - Analytics and crash reporting
• Analytics Integration - User analytics and tracking
• Deploy Android Version - Play Store deployment guide
• Deploy iOS Version - App Store deployment guide
• Logging Multiplatform - Cross-platform logging setup

🛠️ Tech Stack & Libraries

Architecture & Navigation

• Decompose (3.4.0) - Navigation and component lifecycle
• MVIKotlin (4.3.0) - MVI architecture implementation
• Essenty (2.5.0) - Lifecycle management

Dependency Injection

• Koin (4.1.1) - Dependency injection framework

UI Framework

• Compose Multiplatform (1.9.3) - Declarative UI toolkit
• Compose Compiler - Kotlin compiler plugin for Compose

Networking

• Ktor (3.3.2) - HTTP client for networking
  • ktor-client-okhttp for Android
  • ktor-client-darwin for iOS

Data & Storage

• Supabase (3.2.6) - Backend-as-a-Service
• DataStore (1.1.7) - Local data storage
• Kotlinx Serialization (1.9.0) - JSON serialization
• Kotlinx DateTime (0.7.1) - Date and time utilities

Testing

• Kotest (6.0.4) - Testing framework
• Mokkery (2.10.2) - Mocking library

Code Quality & Formatting

• Ktfmt - Kotlin code formatter following official style guide
• Detekt - Static code analysis tool
• Detekt Compose Rules - Compose-specific linting rules

CI/CD & Automation

• GitHub Actions - Configurable CI/CD workflows for testing, building, and deployment
• Danger - Automated PR review and quality checks
• Codecov - Code coverage reporting and analysis

AI Development Assistance

• MCP Servers - Model Context Protocol servers for enhanced AI assistance
• GitHub MCP Server - GitHub integration for AI-powered development
• Context7 MCP Server - Library documentation and code examples access

Feature Flags & Configuration

• ConfigCat (5.1.0) - Feature flags and configuration management
• Firebase Remote Config (2.4.0) - Remote configuration and feature flags

Logging & Monitoring

• Kermit (2.0.8) - Multiplatform logging

Utilities

• Kotlinx Coroutines (1.10.2) - Asynchronous programming
• SLF4J (2.0.17) - Logging facade

🏛️ Architecture

This template follows a clean, scalable architecture:

MVVM + MVI Pattern

• Model: Data and business logic
• View: UI components (Compose/SwiftUI)
• ViewModel: State management and business logic
• Intent: User actions and system events
• State: UI state representation

Component-Based Navigation

• Uses Decompose for navigation and component lifecycle
• Each screen is a separate component
• Shared navigation logic between platforms

Dependency Injection

• Koin for dependency injection
• Shared dependencies in the common module
• Platform-specific implementations

🔧 Configuration

Android Configuration

• Minimum SDK: 26 (Android 8.0)
• Target SDK: 36 (Android 14)
• Compile SDK: 36
• Java Version: 17
• Kotlin JVM Target: 17

iOS Configuration

• Deployment Target: iOS 18.2+
• Swift Version: 5.0
• Xcode Version: 16.0+

Shared Configuration

• Kotlin Version: 2.2.21
• Compose Compiler: Latest
• Coroutines: 1.10.2

🧪 Testing

Running Tests

# Run all tests
./gradlew test

# Run specific module tests
./gradlew :shared:test
./gradlew :composeApp:test

# Run tests with coverage
./gradlew testDebugUnitTestCoverage

For detailed testing information, see Unit Tests Shared and Code Coverage Reports.

🎨 Code Quality

Code Formatting

# Format all code
./gradlew ktfmtFormat

# Check formatting without changes
./gradlew ktfmtCheck

Static Analysis

# Run detekt on all modules
./gradlew detektAll

# Run on specific module
./gradlew :shared:detekt
./gradlew :composeApp:detekt

Pre-commit Hooks

The project includes pre-commit hooks that automatically:

• Format code with ktfmt
• Run detekt analysis
• Block commits with quality issues

Setup:

pip install pre-commit
pre-commit install

For detailed information, see Kotlin Format & Lint, Swift Format & Lint, and Pre-Commit Hooks.

Continuous Integration

The project includes fully configurable GitHub Actions workflows that automatically:

• Run code quality checks on every PR
• Execute unit tests and coverage analysis
• Build and deploy Android and iOS apps
• Validate code formatting and linting

Key Workflows:

• Shared Test & Lint - Code quality and testing on PRs
• Android Deploy - Build, test, and deploy to Play Store
• iOS Deploy - Build, test, and deploy to TestFlight

Automated PR Reviews:

• Danger Kotlin - Configurable PR validation and quality checks
• Automatic label suggestions based on modified files
• Release notes validation for Android deployments
• PR size and description quality enforcement

For detailed information and customization, see GitHub Actions Workflows and Pull Request Checks.

AI-Powered Development

The project includes MCP (Model Context Protocol) servers that enhance AI assistance:

• GitHub Integration - Access repository information, issues, and workflows
• Library Documentation - Quick access to library docs and code examples
• Enhanced AI Context - Better understanding of project structure and dependencies

For setup and configuration, see MCP Servers Configuration.

📦 Building

Android Build

# Debug build
./gradlew assembleDebug

# Release build
./gradlew assembleRelease

# Bundle for Play Store
./gradlew bundleRelease

iOS Build

• Open iosApp/KMP-Template.xcodeproj in Xcode
• Select target device/simulator
• Build using Cmd + B or Product → Build

Shared Framework

# Build shared framework for iOS
./gradlew :shared:assembleXCFramework

🚀 Deployment

Android

1. Update version in composeApp/build.gradle.kts
2. Build release APK or bundle
3. Sign with your release keystore
4. Upload to Google Play Console

For detailed deployment guide, see Deploy Android Version.

iOS

1. Update version in Xcode project
2. Archive the project
3. Upload to App Store Connect

For detailed deployment guide, see Deploy iOS Version.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include your environment details and error logs

🔗 Useful Links

• Kotlin Multiplatform Documentation
• Compose Multiplatform
• Decompose Documentation
• MVIKotlin Documentation
• Koin Documentation

---

Happy coding! 🎉