← Guides

Using Aardink in a web app

Aardink runs in the browser as Kotlin/Wasm through Compose Multiplatform. This page covers the Kotlin side (com.aardarch:aardink-editor-web), turning it into an npm package, using that package from a Vite app, and what the browser verification checklist found.

Before adopting it, read Known limitations: a disposed editor is not fully released until Compose Multiplatform 1.13.

Compose Multiplatform for the web is Beta. Expect the rendering layer underneath Aardink to change between Compose releases.

How the pieces fit

your web app (Svelte/React/...)  ── calls ──▶  your JS exports  (aardinkCreate, aardinkSetValue, ...)
                                                     │  your wasmJs module: binaries.executable()
                                                     ▼
                                          AardinkWeb (com.aardarch:aardink-editor-web)
                                                     │
                                          CodeEditorLayout + languages (:editor, :languages)

There are two ways in:

• Use the ready-built package. pnpm add @aardarch/aardink-web installs :sample-web’s build from npmjs.com, published with every Aardink version from GitHub Actions with npm provenance; pre-releases go to the next tag (pnpm add @aardarch/aardink-web@next). It has the built-in languages and themes and the Monaco-shaped API below, and needs no Gradle or JDK. A language of your own can be registered from JavaScript as a Monarch grammar, with completions, hover and diagnostics answered by your own functions, and a theme as Monaco’s defineTheme data; see Your own languages and themes. Start with Building an npm package for the API and Vite for the bundler set-up; skip the Gradle parts.
• Build your own executable when you need a grammar or language service written in Kotlin: a small Gradle wasmJs module that depends on aardink-editor-web, adds your languages and themes, and declares the @JsExport functions your page calls. That is what lets a product ship its own grammar without Aardink knowing about it. :sample-web in this repository is exactly such a module, and it is the one to copy.

The Kotlin API: AardinkWeb

WebEditorOptions fields: language, theme, fontSize, wordWrap, readOnly, showGutter, showLineNumbers, showFoldMarkers, minimap, stickyScroll, bracketPairColorization, highlightCurrentLine, tabSize, insertSpaces, renderWhitespace, quickSuggestions. An unknown language falls back to plain text and an unknown theme to vscode-dark. Built-in theme keys are in AardinkWeb.builtInThemes. Changing language keeps the text, the selection and the undo history.

Typed and pasted text gets the document’s line endings: those of the text’s first line break when it was set (a CR LF file stays CR LF), LF otherwise. Text a host passes to setValue is kept verbatim.

The export template

Copy editor-web/src/wasmJsTest/kotlin/com/aardarch/aardink/web/ExportsTemplate.kt into your executable module, change its package, and fill in its three marked places: your language registry, your themes and your version string. It lives in Aardink’s test sources so every Aardink build proves it still compiles, and ExportsTemplateTest exercises it. :sample-web’s Exports.kt is the running copy, and :sample-web:verifyExportsMatchTemplate fails the build if the two ever export different functions. The template is not duplicated here because a copy in a document would drift.

Editors cross the JS boundary as integer ids. Every export is prefixed aardink so it cannot collide with your module’s own exports.

With Kotlin 2.4.20, @JsExport functions declared in a dependency klib do end up in the consuming executable’s exports. The template stays the recommended route anyway, because only your module knows your registry and themes.

Building an npm package

:sample-web is the reference for this step; copy its npmPackage Gradle task and src/npm/ folder into your own module.

./gradlew :sample-web:npmPackage     # → sample-web/build/npm, the @aardarch/aardink-web package

The package contains the raw ES modules (kotlin/aardink-web.mjs and friends), both .wasm files, Skiko and the bundled font. It also holds index.js and index.d.ts, which wrap the integer-handle exports in a Monaco-shaped API:

import { createEditor } from '@aardarch/aardink-web';

const editor = await createEditor(container, (text) => save(text), {
  value: source, language: 'xml', theme: 'vscode-dark', wordWrap: 'on',
});
editor.updateOptions({ readOnly: true });
editor.setDiagnostics([{ line: 3, startColumn: 5, endColumn: 9, message: 'Unknown tag', severity: 'error' }]);
const stop = editor.onDidChangeCursor((line, column) => status(line, column));
const off = editor.onDidChangeDiagnostics((markers) => showProblems(markers));
editor.dispose();

createEditor is async: the first call loads the WebAssembly module (~13 MB of .wasm, ~4.7 MB gzipped), and preloadAardink() starts that early. The package depends on @js-joda/core, which Compose’s date/time support imports. Its dependency list is copied from the one Kotlin generates for the module, so it stays accurate.

Vite

// vite.config.js
export default defineConfig({
  // The dev-server pre-bundler rewrites the package into .vite/deps, which breaks the relative
  // new URL('./x.wasm', import.meta.url) references the loader relies on.
  optimizeDeps: { exclude: ['@aardarch/aardink-web'] },
  build: { target: 'es2022', chunkSizeWarningLimit: 3500 },
});

vite build emits both .wasm files and the font as hashed assets. It prints two harmless warnings about node:fs and node:url being externalised: the Kotlin loader has Node and Deno branches that never run in a browser. tools/vite-smoke/ is a complete, minimal example. CI runs it on every change: pnpm smoke builds it and drives it in headless Chrome, failing on any failed check or failed request.

Your own languages and themes

import { createEditor, defineTheme, registerLanguage } from '@aardarch/aardink-web';

await registerLanguage(
  {
    id: 'aardflex',
    extends: 'xml', // XML's completions, diagnostics and folding too
    grammar: {
      tokenPostfix: '.aardflex',
      tokenizer: {
        root: [
          [/<\/?(layer|text)\b/, 'tag'],
          [/[a-z-]+(?==)/, 'attribute.name'],
          [/"[^"]*"/, 'attribute.value'],
        ],
      },
    },
    comments: { blockComment: ['<!--', '-->'] },
  },
  {
    triggerCharacters: ['{', '|', '@'], // besides XML's < / space : " =
    provideCompletionItems: (text, line, column) => [{ label: 'layer', kind: 'element' }],
    provideHover: (text, line, column) => ({ title: 'layer', contents: 'A group of elements.', example: '<layer>…</layer>' }),
    provideDiagnostics: async (text) => validate(text), // AardinkDiagnostic[]
  },
);
await defineTheme('aardflex-dark', {
  base: 'vs-dark',
  inherit: true,
  rules: [{ token: 'tag.aardflex', foreground: 'c586c0' }],
});
const editor = await createEditor(container, save, { language: 'aardflex', theme: 'aardflex-dark' });

• Grammars are a subset of Monaco’s Monarch: states, rules of [regex, action, next?], cases with @array, @default and @eos, capture groups (each with a token name, { token, next } or cases of its own), include, @rematch, defaultToken, ignoreCase, tokenPostfix and @name regex attributes. Not supported: @brackets, nextEmbedded, log, $1-style substitutions in token names, and lookbehind, which is refused when the language is registered because Kotlin/wasm’s regex engine runs it at every position. The grammar highlights a line at a time, so an edit rescans only until the lines below are back in the state they were in. AARDFLEX_WEB_SWITCHOVER.md moves a real Monaco language over this way.
• Colours and font styles follow token names by dotted prefix, as in Monaco: tag.aardflex takes the theme’s tag.aardflex rule, else its tag rule, else the built-in themes’ colour for Monaco’s standard names (keyword, tag, attribute.name, number, delimiter, …). A name with a comment or string part (comment.doc, string.format) is a comment or a string to the editor, as in Monaco: no bracket colours or matching inside it.
• Providers get the whole text and a 1-based position and may answer at once or with a Promise; a provider that throws or rejects gives no answer rather than breaking the editor.
• Completions take Monaco’s item fields label, insertText, insertTextRules, kind, detail, documentation, filterText, sortText and range, in an array or in Monaco’s { suggestions }. The editor does not filter on its own: it asks again on each letter typed while the list is open, so a provider offers what fits what has been typed. An item with filterText is also dropped while what has been typed of it (from the start of its range, or of the word before the caret, to the caret) does not match it; with sortText on any item they are ordered by it. range (Monaco’s IRange, or the replace of { insert, replace }) names exactly what the item replaces; without it the editor replaces the word before the caret, back to the first of < > { } ( ) [ ] " ' = , ; . @ | : or whitespace, which is why @accent typed after @ would otherwise need an insertText of accent. Kinds are element, attribute, value, snippet, module, property, transform (Monaco’s function) and colorRef (color).
• With extends, the extended language’s completions follow yours, less any with the same kind and label as one of yours. inheritCompletions: false in the definition leaves them out (XML’s are Android-flavoured: LinearLayout, android:*, match_parent), keeping its diagnostics, folding and hover; answering { suggestions, exclusive: true } leaves them out for one request. triggerCharacters on the providers open the list when typed, besides the extended language’s, or in place of them with inheritCompletions: false.
• Hover is { title?, contents, example? }: plain text, and example shown as code below it.
• revalidate() collects the language’s diagnostics again at once, for when what your provideDiagnostics depends on outside the text has changed (another file, a setting).

Option names coming from Monaco

Fonts

The browser canvas has no system fonts, so aardink-editor-web bundles JetBrains Mono Regular (SIL Open Font License 1.1; see editor-web/JETBRAINS_MONO_OFL.txt) as a Compose resource. Skia synthesizes the bold and italic the editor occasionally uses.

Compose looks for resources relative to the page, not the module, which a package installed under node_modules never satisfies. So index.js points the font at its own copy with a literal new URL(..., import.meta.url), which is also what makes Vite emit the file. Outside the npm package, call aardinkSetBundledFontUrl(url) before the first aardinkCreate, or serve composeResources/ next to the page. If the font cannot be loaded at all, the editor still works: it logs Aardink: could not load the bundled JetBrains Mono ... and falls back to the default monospace font.

A new editor waits up to half a second for the font before it shows, rather than appearing in the fallback and then jumping to JetBrains Mono (W-9); preloadAardink() starts the fetch early, so usually it waits for nothing. If the font takes longer, the editor shows in the fallback and switches when the font arrives.

Host page CSS

• Size the container. The editor fills it. For a full-height editor on phones use height: 100dvh rather than 100vh, which ignores the browser’s own toolbars.
• The editor follows its container’s size, also when only the container changes: a splitter dragged, or a container that was display: none when the editor was mounted and is shown later. Compose measures on the window’s resize event, so the editor sends one (at most once a frame) whenever its container’s size changes; a page’s own resize listeners see those too.
• The soft keyboard (W-5). With <meta name="viewport" content="width=device-width, initial-scale=1, interactive-widget=resizes-content"> the page shrinks when the keyboard opens, so the editor (and its keyboard toolbar) stay above it; without it, the keyboard covers the bottom of the page. The editor keeps the caret in view either way, and the browser’s hidden input element follows the caret.
• Do not move a mounted editor’s container to another place in the DOM. From Compose Multiplatform 1.13, an editor whose element leaves the document is torn down. Framework features that re-parent DOM nodes (a Svelte {#key} block, React portals moving between parents) do that: mount the editor where it stays, or dispose it and mount a new one.

Browser requirements

Wasm GC and exception handling: Chrome/Edge 119+, Firefox 120+, Safari 18.2+.

Performance

Measured with tools/vite-smoke/perf.mjs in headless Chrome 154 on a desktop machine, on highlighted Kotlin with the language’s own diagnostics running (the 0.6.0 code, 2026-09-27). Expect slower on phones.

• Idle: the time from the event until frames have come at display rate for a third of a second, so it includes every frame the event causes, re-highlighting too.
• Keys lost: a 30-character burst typed at 10 keys a second, about 120 words a minute.

A keystroke costs the same in any size of document: the editor lays out and draws only the lines on screen, the input method sees a window of text around the caret rather than the whole document, and the first highlighting pass over a large document runs in slices of about 8 ms, so frames keep coming while it works. No main-thread task over 50 ms occurs anywhere in these runs: mounting, typing, setValue or scrolling.

The tails are the language’s diagnostics: they run half a second after each pause in typing, as for a user, and perf.mjs pauses longer than that between keys, so a key sometimes arrives while a slice of them is running and waits for it. Before automatic diagnostics (PR 7 of the 0.6 plan), the 5,000-line document measured 8.6 / 18.9 ms per key and 2.6 ms to the change callback. Measurements on a busy machine (a build running alongside) show single 50–60 ms tasks and p95s past 30 ms; the table is from an otherwise idle one.

The minimap (minimap: { enabled: true }) adds 0.1 to 0.5 ms of main-thread work per frame while scrolling the 5,000-line document, and scrolling stays at 60 frames a second: it draws the text as blocks into tiles of 256 lines, kept until a line in them changes, and draws only the tiles on screen.

For comparison, 0.5 (one BasicTextField holding the whole document) took 3.2 s to settle after mounting the same 5,000 lines, 3.7 s after each keystroke, and lost 15 to 29 of 30 keys typed at 10 keys a second.

CI runs perf.mjs --gate on every push; a measurement past its gate fails the build. The gates (400 ms to mount, 50 ms p95 per key, no lost keys, 2 ms per frame for the minimap) are looser than the targets above to absorb shared-runner noise.

Verification checklist

Automated items run against the production build: pnpm checklist in tools/vite-smoke/ covers W-1, part of W-2, W-3, W-7, W-8 and W-10 (node checklist.mjs W-2 W-10 runs a subset), and pnpm perf measures latency and lost keys. The rest need real devices or a person.

Known limitations

• A disposed editor is not fully released (W-1) on Compose Multiplatform 1.12; reuse editors. dispose() takes the editor’s element out of the page, which from 1.13 frees it entirely.
• The console shows “Accessing memory via wasmExports is deprecated” once, when the editor loads its font. Kotlin 2.4.20’s glue logs it the first time anything reads wasmExports.memory, and Compose Multiplatform’s resources library (1.12.1, unchanged in 1.13.0-alpha01) reads it to copy a fetched file into WebAssembly memory. It is harmless and goes away with a Compose Multiplatform release that uses kotlin.wasm.unsafe instead.
• A theme rule’s background is not drawn. Bold and italic come from the bundled font’s own faces where it has them; otherwise the text renderer slants or thickens the regular face.
• The items marked manual in the checklist above wait for real devices before 0.6.0.

Source: docs/WEB_INTEGRATION.mdat v0.8.0.