Crank.js

The Just JavaScript UI Framework

Get Started

Scaffold a new project:

npm create crank

Or try it instantly in the online playground.

Other links: - crank.js.org - NPM - Introducing Crank.js - Examples - Crank for Python - Deep Wiki

Motivation

A framework that feels like JavaScript.

// State is defined with generator components
function* Timer() {
  // setup goes here
  let seconds = 0;
  const interval = setInterval(() => this.refresh(() => seconds++), 1000);

  for ({} of this) {
    yield 

Seconds: {seconds}

;
  }

  clearInterval(interval); // Cleanup just works
}

renderer.render(<Timer />, document.body);

// Async components just work on client and server
async function UserProfile({userId}) {
  const user = await fetchUser(userId);
  return 

Hello, {user.name}!

;
}

await renderer.render(<UserProfile />, document.body);

Why Developers Choose Crank

• Intuitive: Uses async/await for loading states and generator functions for lifecycles. Updates are just execution and control flow makes sense
• Fast: Outperforms React in benchmarks while weighing in at 13.55KB with zero dependencies
• Flexible: Write build-free vanilla JavaScript with template literals or write ergonomic JSX
• Transparent: State lives in function scope. Explicit re-execution means no mysterious why did you render bugs.
• Future-proof: Built on stable JavaScript features, not evolving framework abstractions

The "Just JavaScript" Promise, Delivered

Other frameworks claim to be "just JavaScript" but ask you to think in terms of effects, dependencies, and framework-specific patterns. Crank actually delivers on that promise — your components are literally just functions that use standard JavaScript control flow.

Installation

The Crank package is available on NPM through the @b9g organization (short for bikeshaving).

npm i @b9g/crank

Importing Crank with the automatic JSX transform.

```jsx live /* @jsxImportSource @b9g/crank / import {renderer} from "@b9g/crank/dom";

renderer.render(

This paragraph element is transpiled with the automatic transform.

, document.body, );

### Importing the JSX template tag.

Starting in version `0.5`, the Crank package ships a [tagged template
function](/guides/jsx-template-tag) which provides similar syntax and semantics
as the JSX transform. This allows you to write Crank components in vanilla
JavaScript.

```js live
import {jsx} from "@b9g/crank/standalone";
import {renderer} from "@b9g/crank/dom";

renderer.render(jsx`


No transpilation is necessary with the JSX template tag.


`, document.body);

ECMAScript Module CDNs

Crank is also available on CDNs like jsDelivr (https://cdn.jsdelivr.net/npm/@b9g/crank/) and esm.sh (https://esm.sh/@b9g/crank) for usage in ESM-ready environments.

```jsx live /* @jsx createElement / import {createElement} from "https://cdn.jsdelivr.net/npm/@b9g/crank/crank.js"; import {renderer} from "https://cdn.jsdelivr.net/npm/@b9g/crank/dom.js";

renderer.render(

Running on <a href="https://www.jsdelivr.com">jsDelivr</a>

, document.body, );

## Key Examples

### A Simple Component

```jsx live
import {renderer} from "@b9g/crank/dom";

function Greeting({name = "World"}) {
  return (


Hello {name}


  );
}

renderer.render(<Greeting />, document.body);

A Stateful Component

```jsx live function *Timer(this: Context) { let seconds = 0; const interval = setInterval(() => this.refresh(() => seconds++), 1000); for ({} of this) { yield

Seconds: {seconds}

; }

clearInterval(interval); }

### An Async Component

```jsx live
import {renderer} from "@b9g/crank/dom";
async function Definition({word}) {
  // API courtesy https://dictionaryapi.dev
  const res = await fetch(`https://api.dictionaryapi.dev/api/v2/entries/en/${word}`);
  const data = await res.json();
  if (!Array.isArray(data)) {
    return 

No definition found for {word}

;
  }

  const {phonetic, meanings} = data[0];
  const {partOfSpeech, definitions} = meanings[0];
  const {definition} = definitions[0];
  return <>


{word} <code>{phonetic}</code>




<b>{partOfSpeech}.</b>{" "}{definition}


  </>;
}

await renderer.render(<Definition word="framework" />, document.body);

A Loading Component

```jsx live import {Fragment} from "@b9g/crank"; import {renderer} from "@b9g/crank/dom";

async function LoadingIndicator() { await new Promise(resolve => setTimeout(resolve, 1000)); return (

  🐕 Fetching a good boy...

); }

async function RandomDog({throttle = false}) { const res = await fetch("https://dog.ceo/api/breeds/image/random"); const data = await res.json(); if (throttle) { await new Promise(resolve => setTimeout(resolve, 2000)); }

return (

  <a href={data.message} target="_blank" style="text-decoration: none; color: inherit;">
    <img
      src={data.message}
      alt="A Random Dog"
      width="300"
    />



      Click to view full size



  </a>

); }

async function *RandomDogLoader({throttle}) { // for await can be used to race component trees for await ({throttle} of this) { yield ; yield ; } }

function *RandomDogApp() { let throttle = false; this.addEventListener("click", (ev) => { if (ev.target.tagName === "BUTTON") { this.refresh(() => throttle = !throttle); } });

for ({} of this) { yield (

    <RandomDogLoader throttle={throttle} />



      <button>
        Show me another dog!
      </button>



        {throttle ? "Slow mode" : "Fast mode"}









);

} }

renderer.render(, document.body);

## Common tool configurations
The following is an incomplete list of configurations to get started with Crank.

### [TypeScript](https://www.typescriptlang.org)

TypeScript is a typed superset of JavaScript.

Here’s the configuration you will need to set up automatic JSX transpilation.

```tsconfig.json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@b9g/crank"
  }
}

Crank is written in TypeScript and comes with types. Refer to the guide on TypeScript for more information about Crank types.

import type {Context} from "@b9g/crank";
function *Timer(this: Context<typeof Timer>) {
  let seconds = 0;
  const interval = setInterval(() => this.refresh(() => seconds++), 1000);
  for ({} of this) {
    yield 

Seconds: {seconds}

;
  }

  clearInterval(interval);
}

Babel

Babel is a popular open-source JavaScript compiler which allows you to write code with modern syntax (including JSX) and run it in environments which do not support the syntax.

Here is how to get Babel to transpile JSX for Crank.

Automatic transform:

{
  "plugins": [
    "@babel/plugin-syntax-jsx",
    [
      "@babel/plugin-transform-react-jsx",
      {
        "runtime": "automatic",
        "importSource": "@b9g/crank",

        "throwIfNamespace": false,
        "useSpread": true
      }
    ]
  ]
}

ESLint

ESLint is a popular open-source tool for analyzing and detecting problems in JavaScript code.

Crank provides a configuration preset for working with ESLint under the package name eslint-plugin-crank.

npm i eslint eslint-plugin-crank

In your eslint configuration:

{
  "extends": ["plugin:crank/recommended"]
}

Astro

Astro.js is a modern static site builder and framework.

Crank provides an Astro integration to enable server-side rendering and client-side hydration with Astro.

npm i astro-crank

In your astro.config.mjs.

import {defineConfig} from "astro/config";
import crank from "astro-crank";

// https://astro.build/config
export default defineConfig({
  integrations: [crank()],
});

API Reference

Core Exports

import {
  createElement,
  Fragment,
  Copy,
  Portal,
  Raw,
  Text,
  Context
} from "@b9g/crank";

import {renderer} from "@b9g/crank/dom"; // Browser DOM
import {renderer} from "@b9g/crank/html"; // Server-side HTML

import {jsx, html} from "@b9g/crank/standalone"; // Template tag (no build)

import {Suspense, SuspenseList, lazy} from "@b9g/crank/async";

---

Component Types

Function Component - Stateless

function Greeting({name = "World"}) {
  return 

Hello {name}

;
}

Generator Component - Stateful with function*

function* Counter() {
  let count = 0;
  const onclick = () => this.refresh(() => count++);

  for ({} of this) {
    yield <button onclick={onclick}>Count: {count}</button>;
  }
}

Async Component - Uses async for promises

async function UserProfile({userId}) {
  const user = await fetch(`/api/users/${userId}`).then(r => r.json());
  return 

Hello, {user.name}!

;
}

Async Generator Component - Stateful + async

async function* DataLoader({url}) {
  for ({url} of this) {
    const data = await fetch(url).then(r => r.json());
    yield 

{data.message}

;
  }
}

---

Context API

The context is available as this in components (or as 2nd parameter).

function Component(props, ctx) {
  console.log(this === ctx); // true
  return props.children;
}

Properties

this.props - Current props (readonly)

this.isExecuting - Whether the component is currently executing

this.isUnmounted - Whether the component is unmounted

Methods

this.refresh(callback?) - Trigger re-execution

this.refresh();                    // Simple refresh
this.refresh(() => count++);       // With state update (v0.7+)

this.schedule(callback?) - Execute after DOM is rendered

// el is whatever the component returns Node/Text/HTMLElement/null, an array of dom nodes, etc
this.schedule((el) => {
  console.log("Component rendered", el.innerHTML);
});

this.after(callback?) - Execute after DOM is live

// this runs after the DOM nodes have finally entered the DOM
// this is where you put things like autofocus
this.after((el) => {
  console.log(el.isConnected); // true
});

this.cleanup(callback?) - Execute on unmount

function* Component() {
  const interval = setInterval(() => this.refresh(), 1000);
  this.cleanup(() => clearInterval(interval));

  for ({} of this) {
    yield 

Tick

;
  }
}

this.addEventListener(type, listener, options?) - Listen to events

this.addEventListener("click", (e) => console.log("Clicked!"));

this.dispatchEvent(event) - Dispatch events

this.dispatchEvent(new CustomEvent("mybuttonclick", {
  bubbles: true,
  detail: {id: props.id}
}));

this.provide(key, value) / this.consume(key) - Context API

// Provider
function* ThemeProvider() {
  this.provide("theme", "dark");
  for ({} of this) {
    yield this.props.children;
  }
}

// Consumer
function ThemedButton() {
  const theme = this.consume("theme");
  return <button class={theme}>Click me</button>;
}

Iteration

for ({} of this) - Render loop (sync)

function* Component() {
  for ({} of this) {
    yield 

{this.props.message}

;
  }
}

for await ({} of this) - Async render loop for racing trees

async function* AsyncComponent() {
  for await ({} of this) {
    // Multiple yields race - whichever completes first shows
    yield <Loading />;
    yield <Content />;
  }
}

---

Special Props

key - Unique identifier for reconciliation

<ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>

ref - Access rendered DOM element

<audio ref={(el) => (audio = el)} />

// Forward refs through components
function MyInput({ref, ...props}) {
  return <input ref={ref} {...props} />;
}

copy - Prevent/control re-rendering

// Boolean: prevent rendering when truthy
<li copy={!el.hasChanged}>{el.value}</li>

// string: copy specific props
<input copy="!value" type="text" />        // Copy all except value


                    // Copy only class and id


                    // Copy children

hydrate - Control SSR hydration

                      // Skip hydration
<Portal hydrate={true}>                    // Force hydration
<input hydrate="!value" />                 // Hydrate all except value

class - String or object (v0.7+)

<button class="btn active" />

<button class={{
  btn: true,
  'btn-active': isActive,
  'btn-disabled': isDisabled
}} />

style - CSS string or object

innerHTML - Raw HTML string (⚠️ XSS risk) ```javascript <div innerHTML="<str