Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bikeshaving/crank
The Just JavaScript Framework
https://github.com/bikeshaving/crank
components crank framework generators javascript jsx promises
Last synced: about 1 month ago
JSON representation
The Just JavaScript Framework
- Host: GitHub
- URL: https://github.com/bikeshaving/crank
- Owner: bikeshaving
- License: mit
- Created: 2019-09-05T00:27:50.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-25T03:12:11.000Z (4 months ago)
- Last Synced: 2024-07-18T17:45:14.225Z (about 2 months ago)
- Topics: components, crank, framework, generators, javascript, jsx, promises
- Language: TypeScript
- Homepage: https://crank.js.org
- Size: 20.5 MB
- Stars: 2,683
- Watchers: 40
- Forks: 77
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-github-star - crank
- awesome-list - crank Write JSX-driven components with functions, promises and generators.
- awesome-list - crank - driven components with functions, promises and generators. | bikeshaving | 2402 | (TypeScript)
README
## Try Crank
The fastest way to try Crank is via the [online playground](https://crank.js.org/playground). In addition, many of the code examples in these guides feature live previews.
## 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 **classic** JSX transform.
```jsx live
/** @jsx createElement */
/** @jsxFrag Fragment */
import {createElement, Fragment} from "@b9g/crank";
import {renderer} from "@b9g/crank/dom";
renderer.render(
This paragraph element is transpiled with the classic transform.
,
document.body,
);
```
### 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,
);
```
You will likely have to configure your tools to support JSX, especially if you do not want to use `@jsx` comment pragmas. See below for common tools and configurations.
### 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 [unpkg](https://unpkg.com)
(https://unpkg.com/@b9g/crank?module) and [esm.sh](https://esm.sh)
(https://esm.sh/@b9g/crank) for usage in ESM-ready environments.
```jsx live
/** @jsx createElement */
// This is an ESM-ready environment!
// If code previews work, your browser is an ESM-ready environment!
import {createElement} from "https://unpkg.com/@b9g/crank/crank?module";
import {renderer} from "https://unpkg.com/@b9g/crank/dom?module";
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"
}
}
```
The classic transform is supported as well.
```tsconfig.json
{
"compilerOptions": {
"jsx": "react",
"jsxFactory": "createElement",
"jsxFragmentFactory": "Fragment"
}
}
```
Crank is written in TypeScript. Refer to [the guide on TypeScript](/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(() => {
seconds++;
this.refresh();
}, 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
}
]
]
}
```
Classic transform:
```.babelrc.json
{
"plugins": [
"@babel/plugin-syntax-jsx",
[
"@babel/plugin-transform-react-jsx",
{
"runtime": "class",
"pragma": "createElement",
"pragmaFrag": "''",
"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()],
});
```
## 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
import {renderer} from "@b9g/crank/dom";
function *Timer() {
let seconds = 0;
const interval = setInterval(() => {
seconds++;
this.refresh();
}, 1000);
try {
while (true) {
yield
Seconds: {seconds};
}
} finally {
clearInterval(interval);
}
}
renderer.render(, document.body);
```
### 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} {phonetic}
{partOfSpeech}. {definition}
>;
}
await renderer.render(, 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 (
);
}
async function *RandomDogLoader({throttle}) {
for await ({throttle} of this) {
yield ;
yield ;
}
}
function *RandomDogApp() {
let throttle = false;
this.addEventListener("click", (ev) => {
if (ev.target.tagName === "BUTTON") {
throttle = !throttle;
this.refresh();
}
});
for ({} of this) {
yield (
Show me another dog.
);
}
}
renderer.render(, document.body);
```