Crank Component Authoring

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

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:

1. Component Specification — complete API reference: all component types, lifecycle, context methods, reconciliation, async behavior, special props, JSX modes
2. 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

• Changelog