Tutorial · Web Component

Vanilla · Tiempo estimado: ~12 min · Iteraciones Karajan: 1–2

Este tutorial te lleva desde un directorio vacío hasta una feature mergeada en un pequeño proyecto Web Component vanilla — un Custom Element que puedes embeber en cualquier página HTML sin React / Vue / Svelte. Ideal para design systems, embebibles y demos.

Prerrequisitos

Deberías haber completado el setup común: npm install -g karajan-code, kj init dentro del proyecto y un kj doctor verde. Si kj doctor está rojo, arréglalo antes — kj run se negará a arrancar.

Tutorial

Bootstrapea el proyecto.

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"

Edita package.json para cablear el runner de tests:

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

Añade un vitest.config.js mínimo para el runner de browser:

import { defineConfig } from "vitest/config";

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

Inicializa Karajan en el repo.
Ventana de terminal
```
kj init
kj doctor
```
kj init crea .karajan/ y escribe la configuración del orquestador; kj doctor confirma que los CLIs de los agentes, Docker, Ollama, los puertos y ahora también la descarga de Chromium de Playwright están en su sitio.
Describe la feature en lenguaje natural.

Sin fichero de spec. Sin JSON. Solo la tarea como se la dirías a un compañero:
Ventana de terminal
```
kj run "Crea un Custom Element 'hello-badge' en src/hello-badge.js \
que tome un atributo 'name' y renderice 'Hello, <name>!' dentro de \
un Shadow DOM con una CSS variable --hello-bg para el color de fondo. \
Añade un test Vitest que monte el elemento, ponga name='world' y \
verifique el texto renderizado." \
  --methodology tdd \
  --coder claude \
  --reviewer codex \
  --reviewer-fallback claude \
  --max-iterations 5
```
Con --methodology tdd, Karajan escribe primero el test que falla, luego la implementación, luego re-ejecuta la suite. El reviewer (Codex por defecto, Claude como fallback) revisa el diff buscando buenas prácticas de Custom Element: lifecycle callbacks, attributeChangedCallback, encapsulación del Shadow DOM. Si lo rechaza, Karajan vuelve a llamar al coder — hasta --max-iterations.
Mira el run en el HU Board.

Abre http://localhost:4000 en otra pestaña mientras el pipeline corre. Verás, en tiempo real:
- Cada rol activándose (planner → coder → tester → reviewer).
- El prompt y la respuesta exactos de cada llamada al agente.
- El diff tras cada iteración.
- La salida del test en Chromium headless.
- El veredicto del reviewer.
También puedes hacer tail del mismo trace en el terminal:
Ventana de terminal
```
kj tail
```

Inspecciona el resultado.

git status
git diff --stat
npm test

Salida esperada de 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)

Comprueba a ojo abriendo un index.html rápido:

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

Mergea.

Karajan no hace push ni merge por ti por defecto — esa decisión es tuya. Cuando estés contento con el diff:
Ventana de terminal
```
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
```
O, si quieres que Karajan abra la PR por ti, añade --auto-commit --auto-pr a la invocación kj run.

Errores posibles y cómo resolverlos

Variantes

El mismo run lanzado vía MCP desde cualquier cliente MCP-capable (Cursor, Claude Desktop, Codex):

{
  "tool": "kj_run",
  "params": {
    "task": "Crea un Custom Element 'hello-badge' con atributo 'name' y CSS variable --hello-bg. Añade un test Vitest browser.",
    "methodology": "tdd",
    "coder": "claude",
    "reviewer": "codex",
    "reviewerFallback": "claude",
    "maxIterations": 5
  }
}

Si prefieres Lit para templating + reactive properties:

npm install lit

Y luego lanza con un hint explícito:

kj run "Crea un 'hello-badge' basado en Lit con una propiedad reactiva \
'name'…" \
  --methodology tdd \
  --max-iterations 5

El coder detecta la dependencia Lit y escribe el elemento usando LitElement + @property.

Para un contexto de design system, añade una pasada de validación de tokens:

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

Esto cablea los collectors OSV-Scanner y Semgrep en el audit y gatea el merge contra los checks de accesibilidad (Lighthouse a11y si está disponible).

Siguientes pasos

Otros stacks

Misma receta, distinto bootstrap: Node CLI · Python · REST API (Node) · Java · Go · Rust

Volver al índice

Índice How-To · setup + troubleshooting