Skip to content

Commit 55f4924

Browse files
CopilotShreckYe
Copilot
and
ShreckYe
committed
Add comprehensive .github/copilot-instructions.md for repository onboarding
Co-authored-by: ShreckYe <[email protected]>
1 parent eafafa1 commit 55f4924

File tree

1 file changed

+193
-0
lines changed

1 file changed

+193
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Copilot Instructions for Compose Multiplatform HTML Unified
2+
3+
## Repository Overview
4+
5+
**Compose Multiplatform HTML Unified** is a Kotlin Multiplatform library that provides unified Compose Multiplatform wrappers of common and Material Design APIs for both **rendering-based Compose UI** (Android, desktop JVM, iOS, web Kotlin/Wasm) and **DOM-based Compose HTML**. This library was previously named "Compose Multiplatform Material".
6+
7+
### Repository Statistics
8+
- **Size**: Medium-large multiplatform project with ~15 modules
9+
- **Language**: Kotlin (multiplatform)
10+
- **Build System**: Gradle with Kotlin DSL
11+
- **Target Platforms**: JVM, Android, iOS, JS (DOM), Wasm-JS (Canvas)
12+
- **Key Dependencies**: Compose Multiplatform, Kobweb Silk, Material Web Components
13+
- **Current Version**: 0.6.0-SNAPSHOT
14+
15+
## Build Instructions and Environment Setup
16+
17+
### Prerequisites
18+
- **JDK 17**: Required (as specified in GitHub Actions workflows)
19+
- **Network Access**: Required for initial builds to download Android Gradle Plugin and Kobweb dependencies
20+
- **Gradle 9.0.0**: Automatically handled by wrapper
21+
22+
### Essential Repository Setup
23+
```bash
24+
# The project depends on Kobweb which requires a specific Maven repository
25+
# This is automatically configured in buildSrc/src/main/kotlin/common-conventions.gradle.kts
26+
# Maven repository: https://us-central1-maven.pkg.dev/varabyte-repos/public
27+
```
28+
29+
### Build Commands (In Order)
30+
31+
#### 1. Basic Project Setup
32+
```bash
33+
./gradlew --version # Verify Gradle 9.0.0 and JDK 17
34+
```
35+
36+
#### 2. Publishing to Local Maven (Primary Development Command)
37+
```bash
38+
./gradlew publishToMavenLocal
39+
```
40+
**Important**: Always run `publishToMavenLocal` first when making changes, as mentioned in CONTRIBUTING.md. This publishes libraries to your local Maven repository so dependent projects can use your changes.
41+
42+
#### 3. Running Tests and Checks
43+
```bash
44+
./gradlew check
45+
```
46+
**Note**: The project has "limited number of tests" according to CONTRIBUTING.md, but this validates what exists.
47+
48+
#### 4. Building Demo Applications
49+
```bash
50+
# Build the side-by-side demo (used for GitHub Pages)
51+
./gradlew :compose-multiplatform-html-unified-demo:sideBySideBrowserDistribution
52+
53+
# Individual platform builds
54+
./gradlew jsBrowserDistribution # JS DOM version
55+
./gradlew wasmJsBrowserDistribution # Wasm-JS Canvas version
56+
```
57+
58+
### Build Configuration Details
59+
60+
#### Memory Requirements
61+
- **Gradle JVM**: 2GB memory allocated via `org.gradle.jvmargs=-Xmx2G` in gradle.properties (required for Wasm compilation)
62+
63+
#### Common Build Issues and Workarounds
64+
65+
1. **Network Connectivity**: Initial builds require internet access for Android Gradle Plugin (8.10.1) and Kobweb dependencies. If build fails with network errors, ensure internet connectivity.
66+
67+
2. **Memory Issues**: If Wasm compilation fails with OOM, the memory is already optimized in gradle.properties.
68+
69+
3. **Kotlin/JS Store**: The `kotlin-js-store` directory may be generated during JS builds - this should not be committed.
70+
71+
4. **Gradle Daemon**: May timeout on first runs. Use `--no-daemon` flag if needed: `./gradlew check --no-daemon`
72+
73+
## Project Architecture and Layout
74+
75+
### Module Structure
76+
```
77+
├── common/ # Core APIs, layouts, modifiers (foundation equivalent)
78+
├── material-icons-core/ # Icon system core
79+
├── material2/ # Material Design 2 components
80+
├── material3/ # Material Design 3 components
81+
├── navigation/ # Navigation support (experimental)
82+
├── lifecycle-viewmodel/ # ViewModel support (experimental)
83+
├── demo/ # Demonstration application
84+
└── buildSrc/ # Build configuration and dependencies
85+
```
86+
87+
### Key Configuration Files
88+
- **buildSrc/src/main/kotlin/VersionsAndDependencies.kt**: All dependency versions
89+
- **buildSrc/src/main/kotlin/common-conventions.gradle.kts**: Shared build configuration
90+
- **buildSrc/src/main/kotlin/lib-conventions.gradle.kts**: Library-specific configuration
91+
- **gradle.properties**: JVM memory settings and Kotlin MPP configuration
92+
- **settings.gradle.kts**: Project structure and repository configuration
93+
94+
### Source Set Structure (Per Module)
95+
```
96+
src/
97+
├── commonMain/ # Shared APIs across all platforms
98+
├── composeUiMain/ # Compose UI targets (JVM, Android, iOS, Wasm)
99+
├── composeUiExceptAndroidMain/ # Compose UI excluding Android
100+
├── androidMain/ # Android-specific implementations
101+
├── jsMain/ # JS DOM implementations (Kobweb/HTML)
102+
├── jvmMain/ # Desktop JVM implementations
103+
└── iosMain/ # iOS-specific implementations
104+
```
105+
106+
### CI/CD Workflows
107+
108+
#### `.github/workflows/ci.yml`
109+
- **Trigger**: Push to any branch, manual dispatch
110+
- **Platforms**: ubuntu-latest, macos-latest, windows-latest
111+
- **JDK**: 17-temurin
112+
- **Commands**: Uses `huanshankeji/.github/actions/[email protected]`
113+
114+
#### `.github/workflows/demo-gh-pages.yml`
115+
- **Trigger**: Push/PR to `release` branch, manual dispatch
116+
- **Platform**: ubuntu-latest
117+
- **Purpose**: Builds and deploys demo to GitHub Pages
118+
- **Build Command**: `./gradlew :compose-multiplatform-html-unified-demo:sideBySideBrowserDistribution`
119+
- **Artifact Path**: `demo/build/dist/sideBySide/productionExecutable/`
120+
121+
### Dependencies and External Integration
122+
123+
#### Required External Repositories
124+
```kotlin
125+
repositories {
126+
mavenCentral()
127+
google() // For Android components
128+
maven("https://us-central1-maven.pkg.dev/varabyte-repos/public") // For Kobweb
129+
}
130+
```
131+
132+
#### Key Dependencies
133+
- **Kotlin**: 2.2.0-RC2 with Compose Compiler
134+
- **Compose Multiplatform**: 1.8.1
135+
- **Android Gradle Plugin**: 8.10.1
136+
- **Kobweb**: 0.19.2 (not on Maven Central)
137+
- **Compose HTML Material**: 0.4.0
138+
- **Binary Compatibility Validator**: 0.16.3 (enabled)
139+
140+
### Platform-Specific Implementation Patterns
141+
142+
#### Compose UI Platforms (Android, JVM, iOS, Wasm)
143+
- Delegate directly to official `androidx.compose` APIs
144+
- Located in `composeUiMain` source sets
145+
146+
#### JS DOM Platform
147+
- Built on **Kobweb Silk** (provides Modifier system and layouts)
148+
- Uses **Material Web Components** via Compose HTML Material
149+
- Located in `jsMain` source sets
150+
- Requires CSS imports for Material Icons
151+
152+
### Development Patterns and Conventions
153+
154+
#### API Structure
155+
- **Common APIs**: Defined in `commonMain`, expect/actual pattern for platform differences
156+
- **Ext Components**: Components in `ext` packages don't follow androidx.compose APIs exactly but provide more idiomatic platform-specific wrappers
157+
- **Parameter Naming**: Parameters with "JsDom" or "ComposeUi" suffixes are platform-specific
158+
159+
#### Code Quality and Validation
160+
- **Binary Compatibility**: Enforced via kotlinx.validation plugin
161+
- **Code Style**: IntelliJ IDEA Code Cleanup and Reformat Code applied project-wide
162+
- **Limited Testing**: Project acknowledges "limited number of tests"
163+
164+
### Root Directory Files
165+
```
166+
.gitignore # Standard exclusions plus .kotlin, local.properties
167+
build.gradle.kts # Root build file with binary compatibility validator
168+
CHANGELOG.md # Detailed version history with breaking changes
169+
CODE_OF_CONDUCT.md # Standard code of conduct
170+
CONTRIBUTING.md # Development guidelines and contribution process
171+
gradle.properties # Memory settings and Kotlin configuration
172+
LEGACY_README.md # Previous project name reference
173+
LICENSE # Apache 2.0 license
174+
README.md # Comprehensive API documentation and usage guide
175+
settings.gradle.kts # Project structure and dependency management
176+
```
177+
178+
## Validation Steps for Changes
179+
180+
1. **Build Validation**: Run `./gradlew publishToMavenLocal` to ensure libraries compile
181+
2. **Test Validation**: Run `./gradlew check` to validate existing tests pass
182+
3. **Demo Validation**: Build demo with `./gradlew :compose-multiplatform-html-unified-demo:sideBySideBrowserDistribution`
183+
4. **CI Simulation**: Test on multiple platforms if possible (the CI runs on Ubuntu, macOS, Windows)
184+
5. **Binary Compatibility**: The kotlinx binary compatibility validator will catch API breaks
185+
186+
## Important Notes for Agents
187+
188+
- **Trust These Instructions**: Only perform additional searches if information here is incomplete or incorrect
189+
- **Network Dependency**: Initial builds require internet access - cannot work in fully offline environments
190+
- **Memory Requirements**: Ensure adequate memory for Wasm compilation (2GB JVM heap configured)
191+
- **Kobweb Dependency**: This is the main external dependency not on Maven Central - builds will fail without access to their repository
192+
- **Limited Test Coverage**: Don't expect comprehensive test suites - focus on build and demo validation
193+
- **Platform Complexity**: This is a sophisticated multiplatform project with 6+ target platforms and complex expect/actual patterns

0 commit comments

Comments
 (0)