## Get Started
Scaffold a new project:
```shell
npm create crank
```
Or try it instantly in the [online playground](https://crank.js.org/playground).
Other links:
- [crank.js.org](https://crank.js.org)
- [NPM](https://www.npmjs.com/package/@b9g/crank)
- [Introducing Crank.js](https://crank.js.org/blog/introducing-crank/)
- [Examples](https://github.com/bikeshaving/crank/tree/main/examples)
- [Crank for Python](https://github.com/bikeshaving/crankpy)
- [Deep Wiki](https://deepwiki.com/bikeshaving/crank)
## Motivation
**A framework that feels like JavaScript.**
```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(, 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(, 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](https://npmjs.org/@b9g/crank) through
the [@b9g organization](https://www.npmjs.com/org/b9g) (short for
b*ikeshavin*g).
```shell
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://www.jsdelivr.com)
(https://cdn.jsdelivr.net/npm/@b9g/crank/) and [esm.sh](https://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(
,
document.body,
);
```
## Key Examples
### A Simple Component
```jsx live
import {renderer} from "@b9g/crank/dom";
function Greeting({name = "World"}) {
return (
Hello {name}
);
}
renderer.render(, 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
);
}
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 (
{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](https://crank.js.org/guides/working-with-typescript) for more
information about Crank types.
```tsx
import type {Context} from "@b9g/crank";
function *Timer(this: Context) {
let seconds = 0;
const interval = setInterval(() => this.refresh(() => seconds++), 1000);
for ({} of this) {
yield
Seconds: {seconds}
;
}
clearInterval(interval);
}
```
### [Babel](https://babeljs.io)
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:
```.babelrc.json
{
"plugins": [
"@babel/plugin-syntax-jsx",
[
"@babel/plugin-transform-react-jsx",
{
"runtime": "automatic",
"importSource": "@b9g/crank",
"throwIfNamespace": false,
"useSpread": true
}
]
]
}
```
### [ESLint](https://eslint.org)
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`.
```bash
npm i eslint eslint-plugin-crank
```
In your eslint configuration:
```.eslintrc.json
{
"extends": ["plugin:crank/recommended"]
}
```
### [Astro](https://astro.build)
Astro.js is a modern static site builder and framework.
Crank provides an [Astro integration](https://docs.astro.build/en/guides/integrations-guide/) to enable server-side rendering and client-side hydration with Astro.
```bash
npm i astro-crank
```
In your `astro.config.mjs`.
```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
```javascript
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
```javascript
function Greeting({name = "World"}) {
return
Hello {name}
;
}
```
**Generator Component** - Stateful with `function*`
```javascript
function* Counter() {
let count = 0;
const onclick = () => this.refresh(() => count++);
for ({} of this) {
yield ;
}
}
```
**Async Component** - Uses `async` for promises
```javascript
async function UserProfile({userId}) {
const user = await fetch(`/api/users/${userId}`).then(r => r.json());
return
Hello, {user.name}!
;
}
```
**Async Generator Component** - Stateful + async
```javascript
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).
```javascript
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
```javascript
this.refresh(); // Simple refresh
this.refresh(() => count++); // With state update (v0.7+)
```
**`this.schedule(callback?)`** - Execute after DOM is rendered
```javascript
// 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
```javascript
// 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
```javascript
function* Component() {
const interval = setInterval(() => this.refresh(), 1000);
this.cleanup(() => clearInterval(interval));
for ({} of this) {
yield
# Crank.js
The Just JavaScript UI Framework