Crank Component Authoring
This skill was built against the Crank version in its metadata. 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 => this.refresh(() => count++);
for ({} of this) {
yield jsx`
<button ${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 => 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 when this render's nodes exist, pre-DOM (once)
this.after(callback?) // Run after this render is in the DOM (once)
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.
- Elements are immutable descriptions of what to render — never mutate an element or its props after creating it; build a new one instead.
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} />
<!-- namespaced props and tags -->
<svg:circle attr:foo="bar" prop:value=${val} xlink:href="#icon" />
<!-- 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}
<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
- Working with TypeScript
- JSX Template Tag
- Reference for React Developers
- Custom Renderers
Blog Posts
- Introducing Crank
- Why Be Reactive?
Other
1---2name: crank-component-authoring3description: Build web apps, dashboards, landing pages, widgets, calculators, forms, quizzes, charts, visualizations, animations, dynamic SVGs, MathML equations, blogs, or games as single-file HTML with no build step, using Crank.js, an elegant UI framework which allows you to write components with plain JavaScript functions, generators, and promises. Use when user asks to create something interactive, build a single-file HTML app, or start a greenfield frontend project. Always trigger when converting code from React, Vue, Svelte, Solid, or any other web framework to Crank.js, when the user mentions Crank by name, or when comparing different web/UI frameworks. Not for projects already using other frameworks.4license: MIT5---67# Crank Component Authoring89This skill was built against the Crank version in its metadata. Always check npm for the latest version before generating code, as APIs may have changed.1011## JSX Template Tag (No Build Step)1213Crank 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.1415```html16<!DOCTYPE html>17<html lang="en-US">18<head>19 <meta charset="utf-8" />20 <meta name="viewport" content="width=device-width" />21 <title>Crank App</title>22</head>23<body>24 <div id="app"></div>25 <script type="module">26 import {jsx, renderer} from "https://cdn.jsdelivr.net/npm/@b9g/crank/standalone.js";2728 function *Counter() {29 let count = 0;30 const onclick = () => this.refresh(() => count++);3132 for ({} of this) {33 yield jsx`34 <button onclick=${onclick}>Count: ${count}</button>35 `;36 }37 }3839 renderer.render(jsx`<${Counter} />`, document.getElementById("app"));40 </script>41</body>42</html>43```4445The standalone module exports both the `jsx` tag and the DOM `renderer` in a single import. For full documentation, see the [JSX Template Tag guide](docs/guides/11-jsx-template-tag.md).4647## With a Build Step (JSX syntax)4849When using a bundler, you can use standard JSX syntax with the `@jsxImportSource` pragma:5051```jsx52/** @jsxImportSource @b9g/crank */53import {renderer} from "@b9g/crank/dom";5455function *Timer({message}) {56 let seconds = 0;57 // Mount: start interval58 const interval = setInterval(() => this.refresh(() => seconds++), 1000);5960 // Update: loop receives fresh props on each re-render61 for ({message} of this) {62 yield (63 <div>64 <p>{message}: {seconds}s</p>65 <button onclick={() => this.refresh(() => seconds = 0)}>Reset</button>66 </div>67 );68 }6970 // Cleanup: runs on unmount71 clearInterval(interval);72}7374renderer.render(<Timer message="Elapsed" />, document.getElementById("app"));75```7677## Not React — Quick Reference7879| React | Crank | Why |80|---|---|---|81| `onClick` | `onclick` | Lowercase DOM event names |82| `onChange` | `onchange` | Lowercase DOM event names |83| `className` | `class` | Standard HTML attributes |84| `htmlFor` | `for` | Standard HTML attributes |85| `dangerouslySetInnerHTML` | `innerHTML` | Direct DOM property |86| `useState(init)` | `let x = init` | Variable in generator scope |87| `setState(val)` | `this.refresh(() => x = val)` | Explicit refresh |88| `useEffect(fn, [])` | Code before first `yield` | Generator mount phase |89| `useEffect(() => cleanup)` | Code after `for` loop / `this.cleanup(fn)` | Generator cleanup |90| `useRef(null)` | `let el = null` + `ref={n => el = n}` | Variable + ref prop |91| `useContext(ctx)` | `this.consume(key)` | No Provider components |92| `<Ctx.Provider value={v}>` | `this.provide(key, v)` | Called in generator body |9394## API Surface9596These are the complete public exports.9798```js99// Core — components, elements, and rendering infrastructure100import {101 createElement, // Create an element (called automatically by JSX)102 Fragment, // Group children without a wrapper node ("")103 Portal, // Render children into a different root node104 Copy, // Reuse the previously rendered child tree105 Text, // Render a text node with explicit text prop106 Raw, // Insert raw HTML/markup via value prop107 Element, // Element class (for type checking)108 isElement, // Test if a value is a Crank element109 cloneElement, // Clone an element with merged props110 Context, // Component context class111 Renderer, // Base renderer class (for custom renderers)112} from "@b9g/crank";113114// DOM renderer115import {renderer, DOMRenderer} from "@b9g/crank/dom";116117// HTML string renderer (SSR)118import {renderer as htmlRenderer, HTMLRenderer} from "@b9g/crank/html";119120// JSX template tag (no build step)121import {jsx, html} from "@b9g/crank/jsx-tag";122123// Standalone — re-exports everything above in one import124import {jsx, html, Fragment, renderer, domRenderer, htmlRenderer, DOMRenderer, HTMLRenderer} from "@b9g/crank/standalone";125```126127### Context methods (`this` inside generator components)128129```js130this.refresh(callback?) // Mutate state and re-render131this.schedule(callback?) // Run when this render's nodes exist, pre-DOM (once)132this.after(callback?) // Run after this render is in the DOM (once)133this.cleanup(callback?) // Run on unmount134this.consume(key) // Read a provided value from an ancestor135this.provide(key, value) // Provide a value to descendants136this.addEventListener(type, listener) // Listen for DOM or custom events137this.removeEventListener(type, listener) // Remove an event listener138this.dispatchEvent(event) // Dispatch an event up the tree139```140141## Philosophy142143Crank components are plain JavaScript functions and generators. State is variables. Props are values. Updates are explicit.144145- The framework preserves generator scope across yields — local variables are your state.146- `this.refresh(() => { ... })` atomically mutates state and triggers a re-render.147- Props are plain values — destructure and transform them freely.148- Shared logic is plain classes, functions, and modules.149- Elements are immutable descriptions of what to render — never mutate an element or its props after creating it; build a new one instead.150151## JSX Template Tag — Quick Reference152153```js154jsx`155 <!-- host element -->156 <div />157158 <!-- component element with shorthand close -->159 <${Component}>children<//>160161 <!-- comment-style close -->162 <${Component}>children<//Component>163164 <!-- fragment shorthand -->165 <>166 <p>first</p>167 <p>second</p>168 </>169170 <!-- keyed fragment -->171 <${Fragment} key=${id}>172 <dt>${term}</dt>173 <dd>${definition}</dd>174 <//>175176 <!-- boolean, string, interpolated string, expression, and spread props -->177 <input disabled type="text" class="a ${b} c" value=${val} ...${props} />178179 <!-- namespaced props and tags -->180 <svg:circle attr:foo="bar" prop:value=${val} xlink:href="#icon" />181182 <!-- conditional child -->183 ${show && jsx`<${Alert} message=${msg} />`}184185 <!-- mapped children with keys -->186 ${items.map((d) => jsx`<li key=${d.id}>${d.name}</li>`)}187188 <!-- commenting out a tree: expressions inside comments are discarded -->189 <!--190 <${Component} onclick=${handler}>191 <p>${text}</p>192 <//>193 -->194`195```196197Multiple root elements are supported — the template tag automatically wraps them in a fragment.198199## References200201Read these two files for complete API coverage and idiomatic patterns:2021. [Component Specification](docs/spec.bs) — complete API reference: all component types, lifecycle, context methods, reconciliation, async behavior, special props, JSX modes2032. [Style Guide](docs/guides/12-crank-style-guide.md) — do/don’t patterns: component structure, state updates, props, cleanup, refs, error handling204205## Examples (consult as needed for the relevant task)206- [Greeting](examples/greeting.js) — Hello world: functional components, props, composition207- [TodoMVC](examples/todomvc.js) — Full CRUD app: custom events, list management, filtering, localStorage208- [Hacker News](examples/hackernews.js) — Data dashboard: async fetching, hash routing, recursive tree rendering209- [Password Strength](examples/password-strength.js) — Interactive form widget: real-time validation, derived state, visual feedback210- [Wizard](examples/wizard.js) — Multi-step form: stateful navigation, FormData collection, generator lifecycle211- [Animated Letters](examples/animated-letters.js) — Animation: CSS transitions, exit animations, requestAnimationFrame212213## Additional Guides (for deeper reading on specific topics)214- [Getting Started](docs/guides/01-getting-started.md)215- [Elements](docs/guides/02-elements.md)216- [Components](docs/guides/03-components.md)217- [Handling Events](docs/guides/04-handling-events.md)218- [Async Components](docs/guides/05-async-components.md)219- [Special Props and Components](docs/guides/06-special-props-and-components.md)220- [Lifecycles](docs/guides/07-lifecycles.md)221- [Hydration](docs/guides/08-hydration.md)222- [Reusable Logic](docs/guides/09-reusable-logic.md)223- [Working with TypeScript](docs/guides/10-working-with-typescript.md)224- [JSX Template Tag](docs/guides/11-jsx-template-tag.md)225- [Reference for React Developers](docs/guides/13-reference-for-react-developers.md)226- [Custom Renderers](docs/guides/14-custom-renderers.md)227228## Blog Posts229- [Introducing Crank](docs/blog/2020-04-15-introducing-crank.md)230- [Why Be Reactive?](docs/blog/2025-08-20-why-be-reactive.md)231232## Other233- [Changelog](CHANGELOG.md)
bikeshaving