How-To · Web Component

Vanilla · Estimated time: ~12 min · Karajan iterations: 1–2

This walkthrough takes you from an empty directory to a merged feature on a small vanilla Web Component project — a Custom Element you can embed in any HTML page without React / Vue / Svelte. Perfect for design systems, embeds, and demo pages.

Prerequisites

You should already have done the common setup: npm install -g karajan-code, kj init inside the project, and a green kj doctor. If kj doctor is red, fix that first — kj run will refuse to start otherwise.

Walkthrough

Bootstrap the project.

mkdir hello-wc && cd hello-wc
npm init -y
npm install --save-dev vitest @vitest/browser playwright
git init -b main && git add -A && git commit -m "chore: scaffold"

Edit package.json so the test runner is wired up:

{
  "type": "module",
  "scripts": {
    "test": "vitest run --browser=chromium"
  }
}

Add a minimal vitest.config.js for the browser runner:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    browser: { enabled: true, name: "chromium", provider: "playwright" }
  }
});

Initialize Karajan in the repo.
Terminal window
```
kj init
kj doctor
```
kj init creates .karajan/ and writes the orchestrator config; kj doctor confirms the agent CLIs, Docker, Ollama, ports, and now also that Playwright’s Chromium download is present.
Describe the feature in natural language.

No spec file. No JSON. Just the task as you’d describe it to a colleague:
Terminal window
```
kj run "Create a 'hello-badge' Custom Element in src/hello-badge.js \
that takes a 'name' attribute and renders 'Hello, <name>!' inside a \
Shadow DOM with one CSS variable --hello-bg for the background color. \
Add a Vitest test that mounts the element, sets name='world' and \
asserts the rendered text." \
  --methodology tdd \
  --coder claude \
  --reviewer codex \
  --reviewer-fallback claude \
  --max-iterations 5
```
With --methodology tdd, Karajan writes the failing test first, then the implementation, then re-runs the suite. The reviewer (Codex by default, Claude as fallback) checks the diff for Custom Element best practices: lifecycle callbacks, attributeChangedCallback, Shadow DOM encapsulation. If the reviewer rejects, Karajan loops the coder again — up to --max-iterations.
Watch the run on the HU Board.

Open http://localhost:4000 in another tab while the pipeline runs. You’ll see, in real time:
- Each role activating (planner → coder → tester → reviewer).
- The exact prompt + response of every agent call.
- The diff after each iteration.
- The headless Chromium test output.
- The reviewer verdict.
You can also tail the same trace in the terminal:
Terminal window
```
kj tail
```

Inspect the result.

git status
git diff --stat
npm test

Expected output of npm test:

✓ tests/hello-badge.test.js (1)
  ✓ renders the name attribute in shadow DOM (87ms)

Test Files  1 passed (1)
     Tests  1 passed (1)

Sanity-check visually by opening a quick index.html:

<!DOCTYPE html>
<script type="module" src="./src/hello-badge.js"></script>
<hello-badge name="world" style="--hello-bg: #fdd"></hello-badge>

Merge.

Karajan does not push or merge for you by default — that’s your call. When you’re happy with the diff:
Terminal window
```
git checkout -b feat/hello-badge
git add -A && git commit -m "feat(wc): add <hello-badge> custom element"
git push -u origin feat/hello-badge
gh pr create --fill
```
Or, if you want Karajan to also open the PR for you, add --auto-commit --auto-pr to the kj run invocation.

Possible errors and how to clear them

Variants

The same run launched via the MCP from any MCP-capable client (Cursor, Claude Desktop, Codex):

{
  "tool": "kj_run",
  "params": {
    "task": "Create a 'hello-badge' Custom Element with a 'name' attribute and a --hello-bg CSS variable. Add a Vitest browser test.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

If you prefer Lit for templating + reactive properties:

npm install lit

Then run with an explicit hint:

kj run "Create a Lit-based 'hello-badge' element with a reactive \
'name' property…" \
  --methodology tdd \
  --max-iterations 5

The coder picks up the Lit dependency and writes the element using LitElement + @property.

For a design-system context, add a token-validation pass:

kj run "<task>" \
  --mode strict \
  --enable-security \
  --methodology tdd

This wires the OSV-Scanner and Semgrep collectors into the audit and gates the merge on accessibility checks (Lighthouse a11y if available).

Next steps

Other stacks

Same recipe, different bootstrap: Node CLI · Python · REST API (Node) · Java · Go · Rust

Back to the index

How-To index · setup + troubleshooting