@backtickjs/hono 0.0.0-stage → 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-François Bisson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @backtickjs/hono
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Hono](https://hono.dev) routes as [Backtick](https://backtickjs.com) screens: under `backtick()`, `context.render(<Home />)` answers a request with your server components, bundled for the modules the client that asked provides, as Hono's own `jsxRenderer()` answers with HTML. Each route is a screen, and a path on the client is the same path on the server. Hono is a peer dependency: this package is built against Hono 4.13.13, and works with any later 4.x.
+
+## Install
+
+```sh
+npm install hono @backtickjs/hono @backtickjs/core @backtickjs/bundler
+```
+
+The [repository's README](https://github.com/backtickjs/backtick#packages) says what each package is.
+
+## Usage
+
+```tsx
+import { backtick } from "@backtickjs/hono";
+import { Hono } from "hono";
+import { Home } from "./Home.js";
+
+const app = new Hono();
+
+app.use(backtick());
+app.get("/", (context) => context.render(<Home />));
+
+export default app;
+```
+
+The client sends its modules, each at its package's version, in `x-backtick-modules` (in an Expo app, `modulesOf` from `@backtickjs/core` writes them). The answer is the screen's bundle as CommonJS, `text/javascript`, for the client to run with `execRoot`.
+
+A client without a module the screen needs gets a `426`, and any other refusal of the bundler's a `400`, each with `{ name, message }` as JSON: the client can show why. An error your server components throw passes through to Hono.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { Spliceable, SplicesAs } from "@backtickjs/core";
+import type { MiddlewareHandler } from "hono";
+declare module "hono" {
+    interface ContextRenderer {
+        <T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(input: T): Promise<Response>;
+    }
+}
+/**
+ * Hono's renderer for Backtick screens: under it, `context.render(input)`
+ * answers with `input` bundled for the modules the client sent in
+ * `x-backtick-modules`, so each route is a screen.
+ *
+ *     app.use(backtick());
+ *     app.get("/", (context) => context.render(<Home />));
+ *
+ * A client without a module the screen needs gets a 426, and any other
+ * refusal of the bundler's a 400, each with `{ name, message }`.
+ */
+export declare function backtick(): MiddlewareHandler;

package/dist/index.js

@@ -0,0 +1,39 @@
+import { bundler, BundlerError } from "@backtickjs/bundler";
+/**
+ * Hono's renderer for Backtick screens: under it, `context.render(input)`
+ * answers with `input` bundled for the modules the client sent in
+ * `x-backtick-modules`, so each route is a screen.
+ *
+ *     app.use(backtick());
+ *     app.get("/", (context) => context.render(<Home />));
+ *
+ * A client without a module the screen needs gets a 426, and any other
+ * refusal of the bundler's a 400, each with `{ name, message }`.
+ */
+export function backtick() {
+    return async (context, next) => {
+        context.setRenderer(async (input) => {
+            let modules;
+            try {
+                modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
+            }
+            catch (error) {
+                const { name, message } = error;
+                return context.json({ name, message: `x-backtick-modules isn't JSON: ${message}` }, 400);
+            }
+            try {
+                const build = await bundler.build({ input, modules });
+                const { code } = build.generate({ format: "cjs" });
+                return context.body(code, 200, { "content-type": "text/javascript" });
+            }
+            catch (error) {
+                if (error instanceof BundlerError) {
+                    return context.json({ name: error.name, message: error.message }, error.name === "ClientVersionMismatch" ? 426 : 400);
+                }
+                throw error;
+            }
+        });
+        await next();
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,YAAY,EAAgB,MAAM,qBAAqB,CAAC;AAc1E;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QAC7B,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAClC,IAAI,OAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,oBAAoB,CAAC,IAAI,IAAI,CAAC,CAAC;YACzE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,KAAoB,CAAC;gBAC/C,OAAO,OAAO,CAAC,IAAI,CACjB,EAAE,IAAI,EAAE,OAAO,EAAE,kCAAkC,OAAO,EAAE,EAAE,EAC9D,GAAG,CACJ,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;gBACtD,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnD,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,cAAc,EAAE,iBAAiB,EAAE,CAAC,CAAC;YACxE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;oBAClC,OAAO,OAAO,CAAC,IAAI,CACjB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAC5C,KAAK,CAAC,IAAI,KAAK,uBAAuB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CACnD,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@backtickjs/hono",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.5",
+  "description": "Hono routes as Backtick screens: a route's answer is its server components, bundled for the client that asked",
+  "keywords": [
+    "backtick",
+    "hono",
+    "react-native",
+    "server-driven-ui",
+    "server-components"
+  ],
+  "homepage": "https://backtickjs.com",
+  "bugs": {
+    "url": "https://github.com/backtickjs/backtick/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backtickjs/backtick.git",
+    "directory": "packages/hono"
+  },
+  "license": "MIT",
+  "author": "Jean-François Bisson <jf@backtickjs.com>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/._cache",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@backtickjs/bundler": "^0.2.5",
+    "@backtickjs/core": "^0.2.5"
+  },
+  "peerDependencies": {
+    "hono": "^4.13.13"
+  },
+  "devDependencies": {
+    "hono": "^4.13.13",
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "test": "node --test \"test/**/*.test.ts\"",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
 }

package/src/index.ts

@@ -0,0 +1,55 @@
+import { bundler, BundlerError, type Modules } from "@backtickjs/bundler";
+import type { Spliceable, SplicesAs } from "@backtickjs/core";
+import type { MiddlewareHandler } from "hono";
+
+declare module "hono" {
+  // What `context.render` takes under `backtick()`, as
+  // `jsxRenderer()` types its own.
+  interface ContextRenderer {
+    <T extends [T] extends [SplicesAs<T>] ? unknown : Spliceable>(
+      input: T,
+    ): Promise<Response>;
+  }
+}
+
+/**
+ * Hono's renderer for Backtick screens: under it, `context.render(input)`
+ * answers with `input` bundled for the modules the client sent in
+ * `x-backtick-modules`, so each route is a screen.
+ *
+ *     app.use(backtick());
+ *     app.get("/", (context) => context.render(<Home />));
+ *
+ * A client without a module the screen needs gets a 426, and any other
+ * refusal of the bundler's a 400, each with `{ name, message }`.
+ */
+export function backtick(): MiddlewareHandler {
+  return async (context, next) => {
+    context.setRenderer(async (input) => {
+      let modules: Modules;
+      try {
+        modules = JSON.parse(context.req.header("x-backtick-modules") ?? "{}");
+      } catch (error) {
+        const { name, message } = error as SyntaxError;
+        return context.json(
+          { name, message: `x-backtick-modules isn't JSON: ${message}` },
+          400,
+        );
+      }
+      try {
+        const build = await bundler.build({ input, modules });
+        const { code } = build.generate({ format: "cjs" });
+        return context.body(code, 200, { "content-type": "text/javascript" });
+      } catch (error) {
+        if (error instanceof BundlerError) {
+          return context.json(
+            { name: error.name, message: error.message },
+            error.name === "ClientVersionMismatch" ? 426 : 400,
+          );
+        }
+        throw error;
+      }
+    });
+    await next();
+  };
+}