<div align="center"> <img src="logo.svg" alt="Crank.js Logo" width="200" height="200" />

Crank.js

The Just JavaScript UI Framework

</div>

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 <div>Seconds: {seconds}</div>;
  }

  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 <div>Hello, {user.name}!</div>;
}

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: Comparable to React in benchmarks, lightweight 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.

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

renderer.render(
  <p>This paragraph element is transpiled with the automatic transform.</p>,
  document.body,
);

Importing the JSX template tag.

Starting in version 0.5, the Crank package ships a tagged template function which provides similar syntax and semantics as the JSX transform. This allows you to write Crank components in vanilla JavaScript.

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

renderer.render(jsx`
  <p>No transpilation is necessary with the JSX template tag.</p>
`, 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 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(
  <div id="hello">
    Running on <a href="https://www.jsdelivr.com">jsDelivr</a>
  </div>,
  document.body,
);

Key Examples

A Simple Component

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

function Greeting({name = "World"}) {
  return (
    <div>Hello {name}</div>
  );
}

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

A Stateful Component

function *Timer(this: Context) {
  let seconds = 0;
  const interval = setInterval(() => this.refresh(() => seconds++), 1000);
  for ({} of this) {
    yield <div>Seconds: {seconds}</div>;
  }

  clearInterval(interval);
}

An Async Component

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 <p>No definition found for {word}</p>;
  }

  const {phonetic, meanings} = data[0];
  const {partOfSpeech, definitions} = meanings[0];
  const {definition} = definitions[0];
  return <>
    <p>{word} <code>{phonetic}</code></p>
    <p><b>{partOfSpeech}.</b>{" "}{definition}</p>
  </>;
}

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

A Loading Component

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

async function LoadingIndicator() {
  await new Promise(resolve => setTimeout(resolve, 1000));
  return (
    <div>
      🐕 Fetching a good boy...
    </div>
  );
}

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 (
    <div>
      <a href={data.message} target="_blank" style="text-decoration: none; color: inherit;">
        <img
          src={data.message}
          alt="A Random Dog"
          width="300"
        />
        <div>
          Click to view full size
        </div>
      </a>
    </div>
  );
}

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

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

  for ({} of this) {
    yield (
      <div>
        <RandomDogLoader throttle={throttle} />
        <div>
          <button>
            Show me another dog!
          </button>
          <div>
            {throttle ? "Slow mode" : "Fast mode"}
          </div>
        </div>
      </div>
    );
  }
}

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

Common tool configurations

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

TypeScript

TypeScript is a typed superset of JavaScript.

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

{
  "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 <div>Seconds: {seconds}</div>;
  }

  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 <div>Hello {name}</div>;
}

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 <div>Hello, {user.name}!</div>;
}

Async Generator Component - Stateful + async

async function* DataLoader({url}) {
  for ({url} of this) {