npm - mono-jsx - Versions diffs - 0.0.0-alpha.13 → 0.0.0-alpha.15 - Mend

mono-jsx 0.0.0-alpha.13 → 0.0.0-alpha.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md CHANGED Viewed

@@ -5,7 +5,7 @@
 mono-jsx is a JSX runtime that renders `<html>` element to a `Response` object in JavaScript runtimes like Node.js, Deno, Bun, Cloudflare Workers, etc.
 - No build step needed
-- Lightweight(7KB gzipped), zero dependencies
+- Lightweight(8KB gzipped), zero dependencies
 - Minimal state runtime
 - Streaming rendering
 - Universal, works in Node.js, Deno, Bun, Cloudflare Workers, etc.
@@ -36,14 +36,14 @@ bun add mono-jsx
 ## Setup JSX runtime
-To use mono-jsx as the JSX runtime, add the following configuration to your `tsconfig.json`(`deno.json` for Deno):
+To use mono-jsx as JSX runtime, add the following configuration to your `tsconfig.json`(`deno.json` for Deno):
 ```jsonc
 {
   "compilerOptions": {
-    "allowJs": true, // required for `.jsx` extension in Node.js
     "jsx": "react-jsx",
-    "jsxImportSource": "mono-jsx"
+    "jsxImportSource": "mono-jsx",
+    "allowJs": true // required for `.jsx` extension in Node.js
   }
 }
 ```
@@ -86,6 +86,8 @@ bun run app.jsx
 **Node.js does not support JSX module and declarative fetch server**, we recommend using mono-jsx with [hono](https://hono.dev).
 ```jsx
+// app.jsx
 import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 const app = new Hono();
@@ -214,16 +216,20 @@ function Button() {
 > [!NOTE]
 > the event handler would never be called in server-side. Instead it will be serialized to a string and sent to the client-side. **This means you should NOT use any server-side variables or functions in the event handler.**
-```jsx
-function Button() {
+```tsx
+function Button(this: FC, props: { role: string }) {
   let message = "BOOM!";
+  console.log(message); // only print message in server-side
   return (
     <button
+      role={props.role}
       onClick={(evt) => {
-        Deno.exit(0); // ❌ Deno is unavailable in the browser
-        alert(message); // ❌ message is a server-side variable
-        document.title = "BOOM!"; // ✅ document is a browser API
-        $state.count++; // ✅ $state is the mono-jsx specific usage
+        alert(message); // ❌ `message` is a server-side variable
+        console.log(props.role); // ❌ `props` is a server-side variable
+        Deno.exit(0); // ❌ `Deno` is unavailable in the browser
+        document.title = "BOOM!"; // ✅ `document` is a browser API
+        console.log(evt.target); // ✅ `evt` is the event object
+        this.count++; // ✅ update the state `count`
       }}
     >
       Click Me
@@ -248,79 +254,40 @@ function App() {
 mono-jsx provides a minimal state runtime that allows you to update view based on state changes in client-side.
-```jsx
-function App() {
-  // Initialize the state 'count' with value `0`
-  $state.count = 0;
+```tsx
+function App(
+  this: FC<{ count: number }>,
+  props: { initialCount?: number },
+) {
+  this.count = props.initialCount ?? 0;
   return (
     <div>
       {/* use the state */}
-      <span>{$state.count}</span>
-      {/* computed state */}
-      <span>doubled: {$computed(() => 2 * $state.count)}</span>
+      <span>{this.count}</span>
+      {/* use computed state */}
+      <span>doubled: {this.computed(() => 2 * this.count)}</span>
       {/* update the state in event handlers */}
-      <button onClick={() => $state.count--}>-</button>
-      <button onClick={() => $state.count++}>+</button>
+      <button onClick={() => this.count--}>-</button>
+      <button onClick={() => this.count++}>+</button>
     </div>
   );
 }
 ```
-To support type checking in TypeScript, declare the `State` interface in the global scope:
-```ts
-declare global {
-  interface State {
-    count: number;
-  }
-}
-```
-> [!NOTE]
-> The `$state` and `$computed` are global variables injected by mono-jsx.
-## Using `$context` Hook
-The `$context` hook allows you to access `data` which is set in the root `<html>` element.
-```tsx
-interface Data {
-  foo: string;
-}
-async function App() {
-  const { request, data } = $context<Data>();
-  return (
-    <p>
-      {request.method} {request.url} {data.foo}
-    </p>
-  );
-}
-export default {
-  fetch: (req) => (
-    <html request={req} data={{ foo: "bar" }}>
-      <h1>Hello World!</h1>
-      <App />
-    </html>
-  ),
-};
-```
-> [!NOTE]
-> If you are using hooks in an async function component, you need to call these hooks before any `await` statement.
+> [!WARNING]
+> The state cannot be used in an arrow function component, you should use a `function` declaration instead.
 ```jsx
-async function AsyncApp() {
-  const { request } = $context();
-  const data = await fetchData(new URL(request.url).searchParams.get("id"));
-  const { request } = $context(); // ❌ request is undefined
+// ❌ `this.count++` won't update the view, please use a function declaration instead
+const App = () => {
+  this.count = 0;
   return (
-    <p>
-      {data.title}
-    </p>
+    <div>
+      <span>{this.count}</span>
+      <button onClick={() => this.count++}>+</button>
+    </div>
   );
-}
+};
 ```
 ## Built-in Elements
@@ -331,19 +298,19 @@ mono-jsx provides some built-in elements to help you build your app.
 `<toggle>` element allows you to toggle the visibility of the slotted content.
-```jsx
-function App() {
-  $state.show = false;
+```tsx
+function App(this: FC<{ show: boolean }>) {
+  this.show = false;
   return (
     <div>
-      <toggle value={$state.show}>
+      <toggle value={this.show}>
         <h1>Hello World!</h1>
       </toggle>
-      <button onClick={toggle}>{$computed(() => $state.show ? "Hide" : "Show")}</button>
+      <button onClick={toggle}>{this.computed(() => this.show ? "Hide" : "Show")}</button>
     </div>
   );
   function toggle() {
-    $state.show = !$state.show;
+    this.show = !this.show;
   }
 }
 ```
@@ -352,26 +319,24 @@ function App() {
 `<switch>` element allows you to switch the slotted content based on the `value` property. You need to define the `slot` attribute in the slotted content to match the `value`, otherwise, the default slots will be rendered.
-```jsx
-function App() {
+```tsx
+function App(this: FC<{ lang: "en" | "zh" | "emoji" }>) {
+  this.lang = "en";
   return (
     <div>
-      <switch value={$state.lang}>
+      <switch value={this.lang}>
         <h1 slot="en">Hello, world!</h1>
         <h1 slot="zh">你好，世界！</h1>
         <h1>✋🌎❗️</h1>
       </switch>
-      <button onClick={() => $state.lang = "en"}>English</button>
-      <button onClick={() => $state.lang = "zh"}>中文</button>
+      <button onClick={() => this.lang = "en"}>English</button>
+      <button onClick={() => this.lang = "zh"}>中文</button>
+      <button onClick={() => this.lang = "emoji"}>Emoji</button>
     </div>
   );
 }
 ```
-### `<cache>` element
-_Work in progress..._
 ## Streaming Rendering
 mono-jsx renders your `<html>` as a readable stream, that allows async function components are rendered asynchrously. You can set a `placeholder` attribute to show a loading state while the async component is loading.
@@ -394,7 +359,7 @@ export default {
 };
 ```
-You can also set `rendering` attribute to control the rendering strategy of the async component. Currently, only `eager` is supported that renders the async component immediately.
+You can also set `rendering` attribute to "eager" to render the async component eagerly, which means the async component will be rendered as a sync function component and the `placeholder` will be ignored.
 ```jsx
 async function Sleep(ms) {
@@ -413,3 +378,49 @@ export default {
   ),
 };
 ```
+## Accessing Request Info
+You can access the request info in a function component by using the `request` property in the `this` context. And you must pass the `request` object to the root `<html>` element to make it work.
+```jsx
+function RequestInfo(this: FC) {
+  const { request } = this;
+  return (
+    <div>
+      <h1>Request Info</h1>
+      <p>{request.method}</p>
+      <p>{request.url}</p>
+      <p>{request.headers.get("user-agent")}</p>
+    </div>
+  );
+}
+export default {
+  fetch: (req) => (
+    <html request={req}>
+      <RequestInfo />
+    </html>
+  ),
+};
+```
+## Customizing Response
+You can add `status` or `headers` attribute to the `<html>` element to customize the response.
+```jsx
+export default {
+  fetch: (req) => (
+    <html
+      status={404}
+      headers={{
+        cacheControl: "public, max-age=0, must-revalidate",
+        setCookie: "name=value",
+      }}
+    >
+      <h1>Page Not Found</h1>
+    </html>
+  ),
+};
+```