## 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 Crank?
Crank leans on the language instead of reinventing it. State is a local
variable, held in a generator’s scope. Updates are re-execution: calling
`refresh()` runs the loop again. A loading state is an `async` function,
awaited. Setup is the code before the loop; cleanup is the code after it.
There are no hooks, no dependency arrays, no compiler, and no rules about
what you can call where — control flow is the lifecycle.
Because components are plain functions and generators, everything you already
know about JavaScript applies. Closures hold state, modules share logic, and
`try`/`finally` handles teardown. If you can read JavaScript, you can read a
Crank component.
## 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