Skip to main content

​
Overview

The Lumo UI Plugin uses a lumo.properties file in your project root to configure component generation. This file is created automatically when you run ./gradlew lumo --init.

​
Configuration File

File Name: lumo.properties Location: Project root directory Format: Java Properties file (key=value pairs)

​
Required Properties

​
ThemeName

The name of your application’s theme.
​
ThemeName
String
required
The theme name used throughout your generated components. This should match the name you want to use for your composable theme function.
Example: 
ThemeName=AppTheme
Usage in Generated Code: 
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    content: @Composable () -> Unit
) {
    // Theme implementation
}
Common Values:
  • AppTheme
  • MyAppTheme
  • MainTheme
  • Any valid Kotlin function name

​
ComponentsDir

The relative path from the project root to the directory where component files will be generated.
​
ComponentsDir
String
required
Relative path to the components directory. Must match the package name structure.
Android Example: 
ComponentsDir=app/src/main/java/com/example/app/ui
Kotlin Multiplatform Example: 
ComponentsDir=ui-components/src/commonMain/kotlin/com/example/app/ui
Requirements:
  • Must be a relative path from the project root
  • Directory must exist before generating components
  • The path structure must match the package name
  • Use forward slashes (/) even on Windows
Validation: The plugin validates that the directory path matches the package name structure. For example:
  • ComponentsDir=app/src/main/java/com/example/app/ui
  • PackageName=com.example.app.ui
  • The normalized paths must match: com.example.app.ui

​
PackageName

The package name for generated component files.
​
PackageName
String
required
The fully qualified package name where components will be placed. Must match the directory structure.
Example: 
PackageName=com.example.app.ui
Usage in Generated Code: 
package com.example.app.ui

import androidx.compose.runtime.Composable
// Component implementation
Requirements:
  • Must be a valid Kotlin package name
  • Must match the directory structure in ComponentsDir
  • Can use backticks for special characters (normalized during validation)
Special Cases: 
# Package with backticks (for reserved keywords or special characters)
PackageName=com.example.`app-ui`

# Will be normalized to: com.example.app-ui

​
Optional Properties

​
KotlinMultiplatform

Enable Kotlin Multiplatform support for component generation.
​
KotlinMultiplatform
Boolean
default:"false"
Set to true to generate platform-specific files for Kotlin Multiplatform projects.
Example: 
KotlinMultiplatform=true
When Enabled:
  • Uses multiplatform templates from templates/multiplatform/
  • Generates platform-specific files for different source sets
  • Adapts dependency requirements for Compose Multiplatform
When Disabled (default):
  • Uses Android templates from templates/android/
  • Generates only Android-specific files
  • Uses Android Compose dependencies
Platform-Specific Generation: When KotlinMultiplatform=true, the plugin generates files for:
  • commonMain - Shared code
  • androidMain - Android-specific implementations
  • iosMain - iOS-specific implementations
  • desktopMain - Desktop (JVM) implementations
  • jsMain - JavaScript implementations
  • wasmJsMain - WebAssembly implementations
  • macosMain - macOS-specific implementations

​
Configuration Examples

​
Android Project

# Lumo UI Plugin
# This file is used to store configurations for the Lumo UI Plugin
# Do not delete this file

ThemeName=AppTheme
ComponentsDir=app/src/main/java/com/example/myapp/ui
PackageName=com.example.myapp.ui

​
Kotlin Multiplatform Project

# Lumo UI Plugin
# This file is used to store configurations for the Lumo UI Plugin
# Do not delete this file

ThemeName=AppTheme
ComponentsDir=shared/src/commonMain/kotlin/com/example/shared/ui
PackageName=com.example.shared.ui
KotlinMultiplatform=true

​
Multi-Module Project

# Lumo UI Plugin
# This file is used to store configurations for the Lumo UI Plugin
# Do not delete this file

ThemeName=DesignSystemTheme
ComponentsDir=design-system/src/main/java/com/company/designsystem/components
PackageName=com.company.designsystem.components

​
Default Configuration Template

When you run ./gradlew lumo --init, the following template is created: 
# Lumo UI Plugin
# This file is used to store configurations for the Lumo UI Plugin
# Do not delete this file

ThemeName=AppTheme
ComponentsDir=<<relative-path-to-components-dir-from-root>>
PackageName=<<component-files-package-name>>
# Uncomment this line if you are using Kotlin Multiplatform
# KotlinMultiplatform=false
You must replace the placeholder values before running other commands.

​
Configuration Validation

The plugin validates your configuration before generating components. Validation checks:

​
Directory Existence

Error: The components directory (app/src/main/java/com/example/ui) does not exist.
Solution: Create the directory before running component generation commands.

​
Package Name Mismatch

Warning: The directory (app.src.main.java.com.example.ui) and 
the package name (com.example.app.ui) do not match.
Solution: Ensure the directory structure matches the package name:
  • Directory: app/src/main/java/com/example/app/ui
  • Package: com.example.app.ui

​
Missing Properties

Error: Missing required configs in lumo.properties. 
Expected: [ThemeName, ComponentsDir, PackageName].
Solution: Ensure all required properties are defined in your lumo.properties file.

​
Plugin Not Initialized

Error: The plugin is not setup. Run the plugin with --init to get started.
Solution: Run ./gradlew lumo --init to create the configuration file.

​
Configuration Best Practices

​
1. Use Consistent Naming

Choose a theme name that reflects your application: 
# Good examples
ThemeName=AppTheme
ThemeName=MyCompanyTheme
ThemeName=MaterialTheme

# Avoid
ThemeName=Theme  # Too generic
ThemeName=theme  # Should be PascalCase

​
2. Match Directory Structure

Ensure your directory path exactly matches your package structure: 
# Correct
ComponentsDir=app/src/main/java/com/example/app/ui
PackageName=com.example.app.ui

# Incorrect - will fail validation
ComponentsDir=app/src/main/java/com/example/ui
PackageName=com.example.app.ui

​
3. Use Descriptive Directory Names

# Recommended
ComponentsDir=app/src/main/java/com/example/ui/components
ComponentsDir=app/src/main/java/com/example/designsystem

# Also acceptable
ComponentsDir=app/src/main/java/com/example/ui

​
4. Keep Configuration File in Version Control

Add lumo.properties to your Git repository so team members have the same configuration: 
git add lumo.properties
git commit -m "Add Lumo UI configuration"

​
5. Document Custom Configuration

If you use a non-standard directory structure, add comments: 
# Using a separate UI module for better separation of concerns
ThemeName=DesignSystemTheme
ComponentsDir=modules/design-system/src/main/java/com/example/design/components
PackageName=com.example.design.components

​
Modifying Configuration

You can modify the configuration at any time by editing lumo.properties. Changes take effect immediately for the next command.

​
Changing the Components Directory

  1. Create the new directory
  2. Update ComponentsDir in lumo.properties
  3. Update PackageName to match
  4. Run ./gradlew lumo --setup to verify

​
Migrating from Android to Multiplatform

  1. Update ComponentsDir to point to commonMain
  2. Set KotlinMultiplatform=true
  3. Regenerate components
# Before (Android)
ComponentsDir=app/src/main/java/com/example/ui
PackageName=com.example.ui

# After (Multiplatform)
ComponentsDir=shared/src/commonMain/kotlin/com/example/ui
PackageName=com.example.ui
KotlinMultiplatform=true

​
Troubleshooting Configuration

​
Test Your Configuration

# Verify configuration is valid
./gradlew lumo --setup

# Should output:
# Generating Theme ...
# Generated 'Theme' files: ...

​
View Configuration File Location

The plugin shows the configuration file path in error messages: 
Lumo UI plugin is already initialised. 
The config file can be found here: file:///path/to/project/lumo.properties

​
Reset Configuration

If you need to reset:
  1. Delete lumo.properties
  2. Run ./gradlew lumo --init
  3. Reconfigure with correct values

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us