Crank Component Authoring
Crank 0.7.8+ is required. This skill was built against 0.7.8. Always check npm for the latest version before generating code, as APIs may have changed.
JSX Template Tag (No Build Step)
Crank provides a jsx tagged template literal that runs directly in the browser with no transpiler, no bundler, and no build step. This is the recommended approach for single-file HTML artifacts, prototypes, and demos.
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<title>Crank App</title>
</head>
<body>
<div id="app"></div>
<script type="module">
import {jsx, renderer} from "https://cdn.jsdelivr.net/npm/@b9g/crank/standalone.js";
function *Counter() {
let count = 0;
const onclick = () => this.refresh(() => count++);
for ({} of this) {
yield jsx`
<button onclick=${onclick}>Count: ${count}</button>
`;
}
}
renderer.render(jsx`<${Counter} />`, document.getElementById("app"));
</script>
</body>
</html>
The standalone module exports both the jsx tag and the DOM renderer in a single import. For full documentation, see the JSX Template Tag guide.
With a Build Step (JSX syntax)
When using a bundler, you can use standard JSX syntax with the @jsxImportSource pragma:
/** @jsxImportSource @b9g/crank */
import {renderer} from "@b9g/crank/dom";
function *Timer({message}) {
let seconds = 0;
// Mount: start interval
const interval = setInterval(() => this.refresh(() => seconds++), 1000);
// Update: loop receives fresh props on each re-render
for ({message} of this) {
yield (
<div>
<p>{message}: {seconds}s</p>
<button onclick={() => this.refresh(() => seconds = 0)}>Reset</button>
</div>
);
}
// Cleanup: runs on unmount
clearInterval(interval);
}
renderer.render(<Timer message="Elapsed" />, document.getElementById("app"));
Not React — Quick Reference
| React | Crank | Why |
|---|---|---|
onClick | onclick | Lowercase DOM event names |
onChange | onchange | Lowercase DOM event names |
className | class | Standard HTML attributes |
htmlFor | for | Standard HTML attributes |
dangerouslySetInnerHTML | innerHTML | Direct DOM property |
useState(init) | let x = init | Variable in generator scope |
setState(val) | this.refresh(() => x = val) | Explicit refresh |
useEffect(fn, []) | Code before first yield | Generator mount phase |
useEffect(() => cleanup) | Code after for loop / this.cleanup(fn) | Generator cleanup |
useRef(null) | let el = null + ref={n => el = n} | Variable + ref prop |
useContext(ctx) | this.consume(key) | No Provider components |
<Ctx.Provider value={v}> | this.provide(key, v) | Called in generator body |
API Surface
These are the complete public exports.
// Core — components, elements, and rendering infrastructure
import {
createElement, // Create an element (called automatically by JSX)
Fragment, // Group children without a wrapper node ("")
Portal, // Render children into a different root node
Copy, // Reuse the previously rendered child tree
Text, // Render a text node with explicit text prop
Raw, // Insert raw HTML/markup via value prop
Element, // Element class (for type checking)
isElement, // Test if a value is a Crank element
cloneElement, // Clone an element with merged props
Context, // Component context class
Renderer, // Base renderer class (for custom renderers)
} from "@b9g/crank";
// DOM renderer
import {renderer, DOMRenderer} from "@b9g/crank/dom";
// HTML string renderer (SSR)
import {renderer as htmlRenderer, HTMLRenderer} from "@b9g/crank/html";
// JSX template tag (no build step)
import {jsx, html} from "@b9g/crank/jsx-tag";
// Standalone — re-exports everything above in one import
import {jsx, html, Fragment, renderer, domRenderer, htmlRenderer, DOMRenderer, HTMLRenderer} from "@b9g/crank/standalone";
Context methods (this inside generator components)
this.refresh(callback?) // Mutate state and re-render
this.schedule(callback?) // Run after this render commits (once)
this.after(callback?) // Run after every render commits
this.flush(callback?) // Run after the entire render tree commits
this.cleanup(callback?) // Run on unmount
this.consume(key) // Read a provided value from an ancestor
this.provide(key, value) // Provide a value to descendants
this.addEventListener(type, listener) // Listen for DOM or custom events
this.removeEventListener(type, listener) // Remove an event listener
this.dispatchEvent(event) // Dispatch an event up the tree
Philosophy
Crank components are plain JavaScript functions and generators. State is variables. Props are values. Updates are explicit.
- The framework preserves generator scope across yields — local variables are your state.
this.refresh(() => { ... })atomically mutates state and triggers a re-render.- Props are plain values — destructure and transform them freely.
- Shared logic is plain classes, functions, and modules.
JSX Template Tag — Quick Reference
jsx`
<!-- host element -->
<div />
<!-- component element with shorthand close -->
<${Component}>children<//>
<!-- comment-style close -->
<${Component}>children<//Component>
<!-- fragment shorthand -->
<>
<p>first</p>
<p>second</p>
</>
<!-- keyed fragment -->
<${Fragment} key=${id}>
<dt>${term}</dt>
<dd>${definition}</dd>
<//>
<!-- boolean, string, interpolated string, expression, and spread props -->
<input disabled type="text" class="a ${b} c" value=${val} ...${props} />
<!-- conditional child -->
${show && jsx`<${Alert} message=${msg} />`}
<!-- mapped children with keys -->
${items.map((d) => jsx`<li key=${d.id}>${d.name}</li>`)}
<!-- commenting out a tree: expressions inside comments are discarded -->
<!--
<${Component} onclick=${handler}>
<p>${text}</p>
<//>
-->
`
Multiple root elements are supported — the template tag automatically wraps them in a fragment.
References
Read these two files for complete API coverage and idiomatic patterns:
- Component Specification — complete API reference: all component types, lifecycle, context methods, reconciliation, async behavior, special props, JSX modes
- Style Guide — do/don't patterns: component structure, state updates, props, cleanup, refs, error handling
Examples (consult as needed for the relevant task)
- Greeting — Hello world: functional components, props, composition
- TodoMVC — Full CRUD app: custom events, list management, filtering, localStorage
- Hacker News — Data dashboard: async fetching, hash routing, recursive tree rendering
- Password Strength — Interactive form widget: real-time validation, derived state, visual feedback
- Wizard — Multi-step form: stateful navigation, FormData collection, generator lifecycle
- Animated Letters — Animation: CSS transitions, exit animations, requestAnimationFrame
Additional Guides (for deeper reading on specific topics)
- Getting Started
- Elements
- Components
- Handling Events
- Async Components
- Special Props and Components
- Lifecycles
- Hydration
- [Reusable Logic](guides/09-reusable-logic.m