kuikly-multi-module-config

Kuikly multi-module project management

Contents

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

When multiple modules are needed

A submodule has a Kuikly page (using the @Page annotation) only then is multi-module setup needed. If the submodule has no pages, it is an ordinary KMP module and requires no special configuration.

The core problem solved by multi-module: multiple independent Kuikly modules will cause KuiklyCoreEntry entry class conflicts.

Interactive workflow

When the user asks to create a Kuikly submodule, execute the following steps:

Step 1: Collect information (⚠️ must be completed first, cannot be skipped)

🚨 Mandatory rule: Before performing any configuration operation, you must first ask the user for the submodule name. Even if the user only says "help me create a submodule", youmust first stop and ask what the submodule should be named, and only after obtaining the name can you continue. Absolutely do not assume or make up a submodule name on your own.

Ask the user for the following information (if not provided):

🔴 Must ask (none can be missing; subsequent steps must not be executed before obtaining answers)：

1. Submodule name — Ask the user: "What should your submodule be named?" (English, e.g., kuikly_business）
2. Main module name — Can be confirmed from settings.gradle.kts , and if it cannot be determined, ask the user (usually demo or shared）

After confirming the names, display the following checklist:

Task Progress:
- [x] Step 1: 确认子模块名称 → ${用户提供的名称}
- [x] Step 2: 确认主模块名称 → ${确认的主模块名}
- [ ] Step 3: 创建子模块目录和 build.gradle.kts
- [ ] Step 4: 修改 settings.gradle.kts
- [ ] Step 5: 修改主模块 build.gradle.kts（依赖 + KSP 多模块参数）
- [ ] Step 6: 创建子模块 src 目录结构
- [ ] Step 7: 生成示例页面（@Page）
- [ ] Step 8: 检查是否有多套 Gradle 配置（如有则每套都需配置）

Step 2: Execute configuration

Execute the following configuration in order, and check off the checklist after each step is completed:

2.1 settings.gradle.kts

In the root directory settings.gradle.kts , add the submodule include:

include(":${子模块名}")
// 如果主模块有 buildFileName 配置，子模块也需要：
project(":${子模块名}").buildFileName = buildFileName

2.2 Main module build.gradle.kts

Modify the main module and add two configurations:

// 1. commonMain 依赖中添加子模块
kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation(project(":${子模块名}"))
            }
        }
    }
}

// 2. ksp 块中配置多模块参数
ksp {
    arg("moduleId", "${主模块名}")
    arg("isMainModule", "true")
    arg("subModules", "${子模块名}")      // 多个子模块用 & 分隔
    arg("enableMultiModule", "true")
}

When subModules already exist: append &${子模块名}after the existing value, e.g., "sub1&sub2&${新子模块}"

2.3 Submodule build.gradle.kts

Directly copy the main module's build.gradle.kts to the submodule directory, thenmodify only the following differences, and keep the remaining configuration (plugins, targets, cocoapods, etc.) completely consistent with the main module.

Differences that need to be modified:

// 差异 1：ksp 块 — 修改多模块参数
ksp {
    // 其余参数保持不变...
    arg("moduleId", "${子模块名}")       // ← 改为子模块自己的名称
    arg("isMainModule", "false")         // ← 关键：改为 false
    arg("enableMultiModule", "true")
    // ★ 删除 subModules 参数（子模块不需要）
}

// 差异 2：android.namespace — 改为子模块包名
android {
    namespace = "com.tencent.kuikly.${子模块名}"
}

// 差异 3：commonMain dependencies — 移除对其他子模块的依赖（保留 core、compose 等基础依赖）

For the complete list of differences, see SUBMODULE_CONFIG.md

2.4 Submodule directory structure

${子模块名}/
├── build.gradle.kts
├── src/
│   ├── commonMain/
│   │   ├── kotlin/com/tencent/kuikly/${子模块名}/
│   │   │   └── pages/          # 放 @Page 页面
│   │   └── assets/             # 资源文件（可选）
│   ├── androidMain/            # 以下 *Main 目录根据主模块架构按需创建
│   │   ├── AndroidManifest.xml
│   │   └── kotlin/
│   ├── iosMain/
│   │   └── kotlin/
│   └── jsMain/
│       └── kotlin/

2.5 AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest package="com.tencent.kuikly.${子模块名}"/>

2.6 Generate example page

In the submodule's pages directory, create an example page file to ensure the submodule has at least one @Page page to verify whether the configuration is correct.

For the example page template, see SUBMODULE_CONFIG.md in the "Example Page Template" section.

Page file path:${子模块名}/src/commonMain/kotlin/com/tencent/kuikly/${子模块名}/pages/SamplePage.kt

2.7 Check multiple sets of Gradle configurations (if any, each set needs to be configured)

Some projects maintain multiple sets of Gradle configuration files for different platforms (for example, HarmonyOS separately uses build.ohos.gradle.kts、settings.ohos.gradle.kts), in which case you need to:

1. Check the project root directory and main module directory, and confirm whether there are multiple build.*.gradle.kts or settings.*.gradle.kts files
2. If multiple sets of configurations exist, then all modifications in Steps 3~5 above (submodule build.gradle.kts、settings.gradle.kts, main module KSP parameters, etc.) all need to be inrepeated once in each configuration
3. Submodules also need to be created in multiple corresponding copies build.gradle.kts(such as build.ohos.gradle.kts), and the content is likewise copied from the corresponding main module configuration file and then the differences are modified

💡 How to determine: check whether settings.gradle.kts contains buildFileName -related configuration, or whether there are multiple build.*.gradle.kts files under the main module directory.

For specific adaptation details of the HarmonyOS platform, see MAIN_MODULE_CONFIG.md

Configuration Quick Reference

Configuration Item	Main Module	Submodule
moduleId	Main module name (such as "shared"）	Submodule name (such as "feature_chat"）
isMainModule	"true"	"false"
subModules	All submodule names,& separated	Not required
enableMultiModule	"true"	"true"
commonMain dependency	implementation(project(":子模块"))	Does not depend on the main module

Critical rules

❌ Submodules cannot be compiled independently

Submodules depend on the main module's KuiklyCoreEntry generation 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 classes generated by KSP will conflict.

❌ subModules is only configured in the main module

In the submodule's ksp block,do notconfigure the subModules parameter.

✅ No additional configuration is needed on the iOS side

After the submodule is configured with the cocoapods plugin, Gradle will automatically generate the podspec file,no manual creation is needed. At the same time, in the iOS Podfile,there is no needto introduce the submodule as a separate pod, because the submodule will be compiled together with the main module to generate a single framework (shared.framework）。

✅ It is recommended that the remaining configuration be kept consistent with the main module

The submodule's plugins, kotlin targets, cocoapods, android blocks, and other remaining configurationare recommended to be kept consistent with the main module, to avoid compilation or runtime issues caused by configuration differences. How to do it: directly copy the main module's build.gradle.kts, then modify only the items listed in the difference checklist.

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