Desktop Client Guide

Desktop Client Guide

This guide covers how to use the Compose for Desktop Wizard desktop client to generate your Kotlin Compose Desktop projects.

Installation

See the Installation Guide for detailed setup instructions.

Interface Overview

The desktop client features an organized, simple and responsive interface with several configuration sections:

Header Section

• Application title and branding
• Theme toggle between light and dark modes
• Preview button to view generated files
• Window resize toggle for expanded/compact view

Configuration Sections

1. Project Information

Configure basic project details:

• Application Name (required) - Used for window title and app name
• Package Name (required) - Must not contain spaces or dots (e.g., "codeeditor")
• Version - Project version (default: 1.0.0)

2. UI Configuration

Set default window properties:

• Window Width - Default window width in dp (default: 800)
• Window Height - Default window height in dp (default: 600)

3. Additional Dependencies

Select from 11 optional libraries with interactive cards:

• Hot Reload - Live code updates during development (enabled by default)
• Deskit - Material3 file chooser and dialogs (enabled by default)
• Retrofit + OkHttp - Type-safe HTTP client for API calls
• SQLDelight - Type-safe SQL for local database storage
• Ktor Client - Kotlin-first HTTP client with coroutines
• Decompose - Component-based navigation
• PreCompose - Navigation, ViewModel and DI framework
• Sentry - Error tracking and performance monitoring
• Markdown Renderer - Display and render Markdown content
• Image Loading - Efficient image loading and caching
• kotlinx.datetime - Kotlin multiplatform date/time library

4. Linux Build Configuration

Configure Linux-specific build settings:

• Maintainer - Required for DEBIAN/control file (format: "Name Surname [email protected]")
• Description - App description for package metadata

5. App Icon Selection

Upload custom application icons:

• Drag and drop PNG files directly into the input field (must be 512x512 to avoid conversion errors)
• Browse button to select files using the system file chooser
• Automatic conversion to platform-specific formats (ICO for Windows, ICNS for macOS)
• Falls back to default Compose icons if none are provided

Using the Live Preview

The desktop client includes a real-time preview panel showing generated files:

Preview Tabs

• build.gradle.kts - Complete Gradle build configuration
• settings.gradle.kts - Gradle settings file
• libs.versions.toml - Version catalog with selected dependencies
• Main.kt - Application entry point
• README.md - Project documentation

Project Generation Workflow

1. Configure Project Details

   • Fill in required fields (App Name, Package Name)
   • Set optional version and window dimensions

2. Select Dependencies

   • Choose libraries based on your project needs
   • Hover over dependency cards for descriptions

3. Configure Linux Settings (if targeting Linux)

   • Set maintainer information for proper DEB packaging
   • Add project description

4. Add Custom Icon (optional)

   • Drag the PNG file or use the file browser
   • Preview shows the selected icon

5. Preview Generated Files

   • Review build configuration in preview tabs
   • Verify dependency inclusion and settings

6. Generate Project

   • Click the "Generate Project" button
   • Choose a save location in the file dialog
   • Project generates as a ZIP file

Post-Generation Steps

After extracting your generated project:

Linux & macOS

cd your-project-dir
./gradlew run

Windows

cd your-project-dir
gradlew.bat run

Hot Reload Development (if enabled)

./gradlew :runHot --mainClass YourAppName --auto

Tips and Best Practices

Project Configuration

• Use descriptive app names (shown in window title and dock)
• Keep package names simple without spaces or special characters
• Consider your target platforms when selecting dependencies

Dependency Selection

• Hot Reload is recommended for development workflow
• Deskit provides native file dialogs and system integration
• Choose PreCompose OR Decompose for navigation, not both

Icon Management

• Use high-resolution PNG files (512x512)
• Test generated icons on each target platform

Linux Distribution

• Always fill maintainer information for professional DEB packages
• Use descriptive package descriptions for app stores

Troubleshooting

For common issues and solutions, see the Troubleshooting guide.

Advanced Features

Custom Gradle Tasks

Generated projects include custom tasks for Linux packaging:

• packageDebWithWMClass - Creates DEB with proper desktop integration (Result: self-contained application with JRE bundled)
• generateUpgradeUuid - Creates UUID for Windows MSI upgrades (Make sure to run this task only once and add the generated UUID to the upgradeUuid parameter of the windows block inside of nativeDistributions)

Build Configurations

• Release builds include minimal ProGuard optimization
• Debug builds support hot reload (if enabled)
• Native distributions for all major platforms