Kuikly Multi-module Project Management

When to use multi-module
Interactive workflow
Configuration overview
Critical rules
Detailed config references

When to Use Multi-modules

Multi-module setup is only required if the submodule contains Kuikly pages (using the

@Page

annotation). If the submodule has no pages, it is a regular KMP module and no special configuration is needed.

The core problem solved by multi-modules: Multiple independent Kuikly modules will cause conflicts in the

KuiklyCoreEntry

entry class.

Interactive Workflow

When users request to create a Kuikly submodule, follow these steps:

Step 1: Collect Information (⚠️ Must be completed first, cannot be skipped)

🚨 Mandatory Rule: Before performing any configuration operations, you must first ask the user for the submodule name. Even if the user only says "Help me create a submodule", you must stop and ask what name the submodule should have and proceed only after obtaining the name. Never assume or fabricate the submodule name on your own.

Ask the user for the following information if not provided:

🔴 Must Ask (Indispensable, cannot proceed to subsequent steps without answers):

Submodule Name — Ask the user: "What should your submodule be named?" (In English, e.g.,
```
kuikly_business
```
)
Main Module Name — Can be confirmed from
```
settings.gradle.kts
```
, if unable to determine, ask the user (usually
```
demo
```
or
```
shared
```
)

After confirming the names, display the following checklist:

Task Progress:
- [x] Step 1: Confirm submodule name → ${User-provided name}
- [x] Step 2: Confirm main module name → ${Confirmed main module name}
- [ ] Step 3: Create submodule directory and build.gradle.kts
- [ ] Step 4: Modify settings.gradle.kts
- [ ] Step 5: Modify main module build.gradle.kts (dependencies + KSP multi-module parameters)
- [ ] Step 6: Create submodule src directory structure
- [ ] Step 7: Generate sample page (@Page)
- [ ] Step 8: Check for multiple Gradle configurations (configure each set if present)

Step 2: Execute Configuration

Perform the following configurations in order, and check off the checklist after completing each step:

2.1 settings.gradle.kts

Add the submodule include in the root directory

settings.gradle.kts

kotlin

include(":${submodule name}")
// If the main module has buildFileName configuration, the submodule also needs it:
project(":${submodule name}").buildFileName = buildFileName

2.2 Main Module build.gradle.kts

Modify the main module and add two configurations:

kotlin

// 1. Add submodule to commonMain dependencies
kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(project(":${submodule name}"))
            }
        }
    }
}

// 2. Configure multi-module parameters in the ksp block
ksp {
    arg("moduleId", "${main module name}")
    arg("isMainModule", "true")
    arg("subModules", "${submodule name}")      // Separate multiple submodules with &
    arg("enableMultiModule", "true")
}

When subModules already exists: Append
&${submodule name}
to the existing value, e.g.,
"sub1&sub2&${new submodule}"

2.3 Submodule build.gradle.kts

Directly copy the main module's
build.gradle.kts
to the submodule directory, then only modify the following differences, keep other configurations (plugins, targets, cocoapods, etc.) exactly the same as the main module.

Differences to modify:

kotlin

// Difference 1: ksp block — Modify multi-module parameters
ksp {
    // Keep other parameters unchanged...
    arg("moduleId", "${submodule name}")       // ← Change to the submodule's own name
    arg("isMainModule", "false")         // ← Key: Change to false
    arg("enableMultiModule", "true")
    // ★ Remove the subModules parameter (not needed for submodules)
}

// Difference 2: android.namespace — Change to the submodule's package name
android {
    namespace = "com.tencent.kuikly.${submodule name}"
}

// Difference 3: commonMain dependencies — Remove dependencies on other submodules (keep basic dependencies like core, compose, etc.)

See SUBMODULE_CONFIG.md for the complete difference list.

2.4 Submodule Directory Structure

${submodule name}/
├── build.gradle.kts
├── src/
│   ├── commonMain/
│   │   ├── kotlin/com/tencent/kuikly/${submodule name}/
│   │   │   └── pages/          # Place @Page pages
│   │   └── assets/             # Resource files (optional)
│   ├── androidMain/            # Create the following *Main directories as needed based on the main module architecture
│   │   ├── AndroidManifest.xml
│   │   └── kotlin/
│   ├── iosMain/
│   │   └── kotlin/
│   └── jsMain/
│       └── kotlin/

2.5 AndroidManifest.xml

xml

<?xml version="1.0" encoding="utf-8"?>
<manifest package="com.tencent.kuikly.${submodule name}"/>

2.6 Generate Sample Page

Create a sample page file in the submodule's

pages

directory to ensure the submodule has at least one

@Page

page to verify if the configuration is correct.

See the "Sample Page Template" section in SUBMODULE_CONFIG.md for the sample page template.

Page file path:

${submodule name}/src/commonMain/kotlin/com/tencent/kuikly/${submodule name}/pages/SamplePage.kt

2.7 Check for Multiple Gradle Configurations (Configure Each Set if Present)

Some projects maintain multiple sets of Gradle configuration files for different platforms (e.g., HarmonyOS uses

build.ohos.gradle.kts

and

settings.ohos.gradle.kts

separately). In this case:

Check the project root directory and main module directory to confirm if there are multiple
```
build.*.gradle.kts
```
or
```
settings.*.gradle.kts
```
files
If multiple configurations exist, repeat all modifications from Step 3~5 above (submodule
```
build.gradle.kts
```
,
```
settings.gradle.kts
```
, main module KSP parameters, etc.) in each set of configurations
The submodule also needs to create multiple
```
build.gradle.kts
```
files (e.g.,
```
build.ohos.gradle.kts
```
), whose content is also copied from the corresponding main module configuration file and modified for differences

💡 Judgment Method: Check if there is
buildFileName
related configuration in
settings.gradle.kts
, or if there are multiple
build.*.gradle.kts
files in the main module directory.

See MAIN_MODULE_CONFIG.md for specific adaptation details for HarmonyOS.

Configuration Cheat Sheet

Configuration Item	Main Module	Submodule
`moduleId`	Main module name (e.g., `"shared"` )	Submodule name (e.g., `"feature_chat"` )
`isMainModule`	`"true"`	`"false"`
`subModules`	All submodule names, separated by `&`	Not needed
`enableMultiModule`	`"true"`	`"true"`
commonMain dependencies	`implementation(project(":submodule"))`	No dependency on main module

Critical Rules

❌ Submodules Cannot Be Compiled Independently

Submodules depend on the

KuiklyCoreEntry

generated by the main module and cannot exist independently. They must be compiled through the main module.

❌ moduleId Must Be Unique

Each module's

moduleId

must be different, otherwise the entry class generated by KSP will conflict.

❌ subModules Only Configured in Main Module

Do not configure the

subModules

parameter in the ksp block of submodules.

✅ No Additional Configuration Required for iOS

After the submodule configures the

cocoapods

plugin, Gradle will automatically generate the podspec file, no manual creation needed. Meanwhile, there is no need to separately import the submodule via pod in the iOS Podfile, because the submodule will be compiled together with the main module into a single framework (

shared.framework

✅ Other Configurations Are Recommended to Be Consistent with Main Module

It is recommended that other configurations of the submodule, such as plugins, kotlin targets, cocoapods, android block, etc., be consistent with the main module to avoid compilation or runtime issues caused by configuration differences. Operation method: Directly copy the main module's

build.gradle.kts

, then only modify the items listed in the difference list.

Detailed Guides

Complete submodule configuration template (build.gradle.kts + directory structure): SUBMODULE_CONFIG.md
Main module modification guide (dependencies, KSP adaptation): MAIN_MODULE_CONFIG.md

kuikly-multi-module-config

NPX Install

Tags

SKILL.md Content (Chinese)

Kuikly Multi-module Project Management

Contents

When to Use Multi-modules

Interactive Workflow

Step 1: Collect Information (⚠️ Must be completed first, cannot be skipped)

Step 2: Execute Configuration

2.1 settings.gradle.kts

2.2 Main Module build.gradle.kts

2.3 Submodule build.gradle.kts

2.4 Submodule Directory Structure

2.5 AndroidManifest.xml

2.6 Generate Sample Page

2.7 Check for Multiple Gradle Configurations (Configure Each Set if Present)

Configuration Cheat Sheet

Critical Rules

❌ Submodules Cannot Be Compiled Independently

❌ moduleId Must Be Unique

❌ subModules Only Configured in Main Module

✅ No Additional Configuration Required for iOS

✅ Other Configurations Are Recommended to Be Consistent with Main Module

Detailed Guides