Skip to main content

Getting started

Add the dependency​

kotlin {
js {
browser()
}
sourceSets {
jsMain.dependencies {
implementation("io.github.shijianjs:ktjs-dom-kit:0.1.0")
}
}
}

kotlin-browser and kotlin-csstype come with it as api dependencies: the public surface is spelled in their types (web.html.HTMLElement, csstype.Properties), so a project that already uses kotlin-wrappers needs no second set of DOM types.

A first element​

A component is a class extending CustomElementAdapter, a tag name, and one defineIfMissing call:

class KtjsChip : CustomElementAdapter() {
private val label = HtmlTagName.span.createElement {
inlineStyle.display = Display.block
}

/** `text`: the chip's caption. */
@JsName("text")
var text: String by attr { change -> label.textContent = change.newValue }

init {
// The constructor may not touch `this`, but the shadow root is its own tree.
val shadow = attachStyledShadow(SHEET)
shadow.appendChild(label)
}

override fun connectedCallback() {
// Markup that was already parsed never reached the property setter above.
applyInitialAttributes()
}

companion object : CustomElementReference<KtjsChip>(KtjsChip::class.js) {
val NAME: TagName<KtjsChip> = TagName("ktjs-chip")

private val SHEET: CSSStyleSheet = cssSheet {
":host" {
display = Display.block
padding = Padding(0.5.rem)
}
}
}
}

fun registerKtjsChip() = defineIfMissing(KtjsChip.NAME, KtjsChip.Companion)

defineIfMissing strips the compiler-generated forwarding bridges from the class before it registers the tag, which is what lets the element body call appendChild / querySelectorAll under their normal names. Skipping it leaves an element whose first DOM call recurses until the stack overflows — see Custom elements for what is going on.

The element now takes markup and attributes like any other:

<ktjs-chip text="0.1.0"></ktjs-chip>
<script type="module" src="./ktjs-chip.mjs"></script>

Working in this repository​

The build is a Gradle multi-project build; the library module is ktjs-dom-kit and the site is docs.

./gradlew build # compile, Detekt, browser tests
./gradlew :ktjs-dom-kit:jsBrowserTest
./gradlew :docs:docusaurusBuild # the documentation site
./gradlew pagesSite # documentation at /, Dokka at /api/
./gradlew :docs:docusaurusStart # dev server

build does not assemble the Pages site: that is what the Pages workflow runs.

PathContents
package.jsonthe only place npm versions are declared (Dependabot maintains it)
ktjs-dom-kit/src/jsMain/kotlinthe library declarations
ktjs-dom-kit/src/jsTest/kotlinbrowser tests for them
docs/src/jsMain/kotlinthe site configuration and sidebars
docs/src/jsMain/resourcesMarkdown pages, the MDX landing page, CSS, translations

Chromium is downloaded by Playwright the first time a browser test runs; the tests themselves need JDK 21 and nothing else, because the Kotlin Gradle plugin installs npm for the workspace.

The lock file​

npm dependencies are resolved once for the whole workspace and pinned in kotlin-js-store/package-lock.json. After adding or upgrading an npm dependency — or changing a module's version — regenerate it:

./gradlew kotlinUpgradePackageLock

CI verifies the committed file, so a forgotten regeneration fails the build rather than drifting.