@bikeshaving/crank

Crank.js

Write JSX-driven components with functions, promises and generators.

Documentation is available at crank.js.org. Crank.js is in a beta phase, and some APIs may change. To read more about the motivations for this library, you can read the introductory blog post.

Features

Declarative components

Crank uses the same JSX syntax and diffing algorithm popularized by React, allowing you to write HTML-like code directly in your JavaScript.

Just JavaScript™

All components in Crank are just functions or generator functions. No classes, hooks, proxies or template languages are needed.

Promises today

Crank provides first-class support for promises. You can use async/await directly in components, and race components to display fallback UIs.

Installation

Crank is available on NPM in the ESModule and CommonJS formats.

$ npm install @bikeshaving/crank

/** @jsx createElement */
import {createElement} from "@bikeshaving/crank";
import {renderer} from "@bikeshaving/crank/dom";

renderer.render(<div id="hello">Hello world</div>, document.body);

If your environment does not support ESModules (you’ll probably see a message like SyntaxError: Unexpected token export), you can import the CommonJS versions of the library under the cjs directory.

/** @jsx createElement */
import {createElement} from "@bikeshaving/crank/cjs";
import {renderer} from "@bikeshaving/crank/cjs/dom";

renderer.render(<div id="hello">Hello world</div>, document.body);

Key Examples

A Simple Component

/** @jsx createElement */
import {createElement} from "@bikeshaving/crank";
import {renderer} from "@bikeshaving/crank/dom";

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

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

Try on CodeSandbox

A Stateful Component

/** @jsx createElement */
import {createElement} from "@bikeshaving/crank";
import {renderer} from "@bikeshaving/crank/dom";

function *Timer() {
  let seconds = 0;
  const interval = setInterval(() => {
    seconds++;
    this.refresh();
  }, 1000);
  try {
    while (true) {
      yield <div>Seconds: {seconds}</div>;
    }
  } finally {
    clearInterval(interval);
  }
}

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

Try on CodeSandbox

An Async Component

/** @jsx createElement */
import {createElement} from "@bikeshaving/crank";
import {renderer} from "@bikeshaving/crank/dom";

async function QuoteOfTheDay() {
  const res = await fetch("https://favqs.com/api/qotd");
  const {quote} = await res.json();
  return (
    <p>
      “{quote.body}” – <a href={quote.url}>{quote.author}</a>
    </p>
  );
}

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

Try on CodeSandbox

A Loading Component

/** @jsx createElement */
import {createElement, Fragment} from "@bikeshaving/crank";
import {renderer} from "@bikeshaving/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 (
    <a href={data.message}>
      <img src={data.message} alt="A Random Dog" width="300" />
    </a>
  );
}

async function *RandomDogLoader({throttle}) {
  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") {
      throttle = !throttle;
      this.refresh();
    }
  });

  while (true) {
    yield (
      <Fragment>
        <div>
          <button>Show me another dog.</button>
        </div>
        <RandomDogLoader throttle={throttle} />
      </Fragment>
    );
  }
}

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

Try on CodeSandbox

Changelog

[0.2.0] - 2020-07-01

Changed

• Props are no longer rememebered between renders. For instance, rendering <input checked /> and then <input /> will not cause the checked prop to be deleted on the actual element.
• The internal Renderer API has been changed to use inheritance and away from the intrinsic generator API.
• Renderer.prototype.render and Context.prototype.refresh now return rendered values rather than undefined.
• The library is no longer transpiled.
• The esm directory in the package has been deleted. Refer to index, dom and html in the root of the package instead.
• Some types have been simplified
  • Tag no longer takes a type parameter.
  • The types Props, FunctionComponent, GeneratorComponent, IntrinsicProps, ChildIterator, ChildGenerator and Key have been removed from the public API.

Added

• UMD build.
• crank-ref props.
• Context.prototype.schedule.
• Context.prototype.cleanup.
• Context.prototype.props.
• Context.prototype.value.
• dispatchEvent now does bubbling and capturing correctly.

Fixed

• Performance improvements in terms of execution time, runtime memory costs, and library size.
• Fixed Context.prototype.dispatchEvent not responding to stopPropagation and stopImmediatePropagation.
• Fixed nested SVG elements not rendering SVGElements in some cases.
• Improved error handling.