@b9g/crank 0.5.6 → 0.6.0

package/README.md

@@ -1,19 +1,216 @@
-# Crank.js
-### The Just JavaScript web framework.
+## Try Crank
 
-Crank is a web framework where components can be defined with sync functions, async functions and generator functions. The documentation for Crank.js is available at [crank.js.org](https://crank.js.org).
+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.
 
-## Get Started
+## Installation
 
-Crank.js is published on NPM under the `@b9g` organization (short for “b*ikeshavin*g”).
+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
+npm i @b9g/crank
 ```
 
-### Key Examples
+### Importing Crank with the **classic** JSX transform.
 
-#### A Simple Component
+```jsx live
+/** @jsx createElement */
+/** @jsxFrag Fragment */
+import {createElement, Fragment} from "@b9g/crank";
+import {renderer} from "@b9g/crank/dom";
+
+renderer.render(
+  <p>This paragraph element is transpiled with the classic transform.</p>,
+  document.body,
+);
+```
+
+### Importing Crank with the **automatic** JSX transform.
+
+```jsx live
+/** @jsxImportSource @b9g/crank */
+import {renderer} from "@b9g/crank/dom";
+
+renderer.render(
+  <p>This paragraph element is transpiled with the automatic transform.</p>,
+  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`
+  <p>No transpilation is necessary with the JSX template tag.</p>
+`, 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(
+  <div id="hello">
+    Running on <a href="https://unpkg.com">unpkg.com</a>
+  </div>,
+  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 <div>Seconds: {seconds}</div>;
+  }
+
+  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";
@@ -27,7 +224,7 @@ function Greeting({name = "World"}) {
 renderer.render(<Greeting />, document.body);
 ```
 
-#### A Stateful Component
+### A Stateful Component
 
 ```jsx live
 import {renderer} from "@b9g/crank/dom";
@@ -50,22 +247,28 @@ function *Timer() {
 renderer.render(<Timer />, document.body);
 ```
 
-#### An Async Component
+### 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 <p>No definition found for {word}</p>;
+  }
 
-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>
-  );
+  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>
+  </>;
 }
 
-renderer.render(<QuoteOfTheDay />, document.body);
+await renderer.render(<Definition word="framework" />, document.body);
 ```
 
 ### A Loading Component
@@ -112,10 +315,10 @@ function *RandomDogApp() {
   for ({} of this) {
     yield (
       <Fragment>
-        <div>
-          <button>Show me another dog.</button>
-        </div>
         <RandomDogLoader throttle={throttle} />
+        <p>
+          <button>Show me another dog.</button>
+        </p>
       </Fragment>
     );
   }