@backtickjs/bun-plugin 0.1.0

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

@@ -0,0 +1,69 @@
+# @backtickjs/bun-plugin
+
+Runs a Backtick server on Bun without a build step. It's a Bun plugin, preloaded, that compiles your server's TypeScript and JSX files as they load, including their `cs` client scripts and the framework compile steps your project names. Use it in development and in production when Bun is your runtime; on Node, use [`@backtickjs/node-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/node-plugin) instead.
+
+## Install
+
+```sh
+bun add @backtickjs/bun-plugin typescript
+```
+
+It's a runtime dependency: the server needs it whenever it starts. Requires TypeScript 6.
+
+## Usage
+
+Preload it from `bunfig.toml`:
+
+```toml
+preload = ["@backtickjs/bun-plugin"]
+```
+
+or from the command line:
+
+```sh
+bun --preload @backtickjs/bun-plugin server/index.tsx
+```
+
+Run it from the project root: the plugin reads `package.json` from the current directory. In development, add `--watch` to restart the server when a file changes:
+
+```sh
+bun --watch --preload @backtickjs/bun-plugin server/index.tsx
+```
+
+What it does:
+
+- Compiles every `.ts` and `.tsx` file outside `node_modules`, each with the `tsconfig.json` nearest to it, so a server and an app beside it can each have their own. (Bun alone reads only the root `tsconfig.json`.)
+- Compiles each `cs` script in those files, with the framework compile steps named in `package.json` (below). A script the compiler refuses throws its error, and the file doesn't load.
+
+## Configuration
+
+Name your framework's compile steps in the project's `package.json`:
+
+```json
+{
+  "backtick": {
+    "plugins": ["@backtickjs/react/plugin"]
+  }
+}
+```
+
+Use `@backtickjs/solid-js/plugin` for Solid. The steps are loaded once, at startup, with the project's own `require`.
+
+Compiler options come from the nearest `tsconfig.json`, following `extends`. The plugin always emits ES modules (`ESNext`) with an inline source map, and ignores `outDir`, `rootDir` and other output-location options.
+
+## Notes
+
+- The plugin compiles; it doesn't type-check. Run [`backtick-tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc) for that.
+- For stack traces that point at your files, the plugin stamps a `// @bun` pragma on its output so Bun uses its inline source map. This relies on undocumented Bun behavior and could break on a Bun upgrade.
+- With that pragma, Bun reads the output as Latin-1, so the plugin escapes every non-ASCII character as `\uXXXX`. Strings and identifiers keep their meaning, but stack-trace columns after non-ASCII text on the same line may be off; line numbers stay right.
+- Files under `node_modules` are handed back to Bun uncompiled.
+
+## Related
+
+- [`@backtickjs/node-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/node-plugin): the same for Node
+- [`@backtickjs/tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc): type-checks scripts and their splices
+- [Documentation](https://backtickjs.com/docs)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { compileModule, pluginsFrom } from "@backtickjs/compiler";
+import { plugin } from "bun";
+import ts from "typescript";
+const packageJson = path.join(process.cwd(), "package.json");
+const plugins = pluginsFrom(readFileSync(packageJson, "utf8"), createRequire(packageJson));
+/**
+ * Use it from a `bunfig.toml`:
+ *
+ * ```toml
+ * preload = ["@backtickjs/bun-plugin"]
+ * ```
+ *
+ * or from the command line:
+ *
+ * ```sh
+ * bun --preload @backtickjs/bun-plugin ./src/index.ts
+ * ```
+ *
+ * The framework's compile steps are the project's, named in its
+ * `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] }
+ * ```
+ */
+plugin({
+    name: "backtick",
+    setup(build) {
+        build.onLoad({ filter: /\.tsx?$/ }, (args) => {
+            const source = readFileSync(args.path, "utf8");
+            // What the project installed is left to Bun. Returning `undefined` here
+            // throws on Bun >= 1.3 ("onLoad() expects an object returned"), so hand
+            // back the original source with a plain TS/TSX loader instead.
+            if (args.path.includes("node_modules")) {
+                return {
+                    contents: source,
+                    loader: args.path.endsWith(".tsx") ? "tsx" : "ts",
+                };
+            }
+            // The project's own files are all compiled here, not only those with a
+            // script: Bun reads only the root `tsconfig.json`, and a server beside an
+            // app has its own, nearer one.
+            const fileName = path.relative(process.cwd(), args.path).split(path.sep).join("/") ||
+                args.path;
+            const code = compileModule(ts, fileName, source, { plugins });
+            return {
+                contents: ascii(stampBun(code)),
+                loader: args.path.endsWith(".tsx") ? "jsx" : "js",
+            };
+        });
+    },
+});
+// Code with every character past ASCII escaped, `\uXXXX`: Bun reads a file
+// stamped `// @bun` (below) as Latin-1, as its own transpiler writes them, so
+// "🏡" would arrive as "ð\u009f\u008f¡". Escaped, a string, identifier or
+// regular expression means what it did. (JSX text doesn't read escapes, but
+// what reaches here is JSX compiled to calls unless a project preserves it.)
+// The source map isn't shifted to match, so columns after an escape on its
+// line are off; lines stay right, which is worth it for text that reads right.
+function ascii(code) {
+    return code.replace(/[^\x00-\x7f]/g, (unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+// HACK: stamp a `// @bun` pragma at the top of the output to trick Bun into
+// using our inline source map.
+//
+// This relies on undocumented Bun internals and could break on any Bun upgrade.
+// The proper fix would be a real Bun plugin API for handing back a source map.
+//
+// Bun reads the pragma only on the very first line, so it's written into the
+// text rather than onto the first statement, where a leading comment would push
+// it down. The map gains an empty first line to match.
+const MAP = "//# sourceMappingURL=data:application/json;base64,";
+function stampBun(code) {
+    const at = code.lastIndexOf(MAP);
+    if (at === -1) {
+        return `// @bun\n${code}`;
+    }
+    const map = JSON.parse(Buffer.from(code.slice(at + MAP.length).trim(), "base64").toString("utf8"));
+    map.mappings = `;${map.mappings}`;
+    const encoded = Buffer.from(JSON.stringify(map)).toString("base64");
+    return `// @bun\n${code.slice(0, at)}${MAP}${encoded}\n`;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@backtickjs/bun-plugin",
+  "version": "0.1.0",
+  "description": "Runs a Backtick server on Bun without a build step, compiling its files and client scripts as they load",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "server-driven-ui",
+    "server-components",
+    "bun",
+    "plugin",
+    "loader"
+  ],
+  "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/bun-plugin"
+  },
+  "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/compiler": "0.1.0"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.3",
+    "@backtickjs/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "bun test",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { compileModule, pluginsFrom } from "@backtickjs/compiler";
+import { plugin } from "bun";
+import ts from "typescript";
+
+const packageJson = path.join(process.cwd(), "package.json");
+const plugins = pluginsFrom(
+  readFileSync(packageJson, "utf8"),
+  createRequire(packageJson),
+);
+
+/**
+ * Use it from a `bunfig.toml`:
+ *
+ * ```toml
+ * preload = ["@backtickjs/bun-plugin"]
+ * ```
+ *
+ * or from the command line:
+ *
+ * ```sh
+ * bun --preload @backtickjs/bun-plugin ./src/index.ts
+ * ```
+ *
+ * The framework's compile steps are the project's, named in its
+ * `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] }
+ * ```
+ */
+plugin({
+  name: "backtick",
+  setup(build) {
+    build.onLoad({ filter: /\.tsx?$/ }, (args) => {
+      const source = readFileSync(args.path, "utf8");
+
+      // What the project installed is left to Bun. Returning `undefined` here
+      // throws on Bun >= 1.3 ("onLoad() expects an object returned"), so hand
+      // back the original source with a plain TS/TSX loader instead.
+      if (args.path.includes("node_modules")) {
+        return {
+          contents: source,
+          loader: args.path.endsWith(".tsx") ? "tsx" : "ts",
+        };
+      }
+
+      // The project's own files are all compiled here, not only those with a
+      // script: Bun reads only the root `tsconfig.json`, and a server beside an
+      // app has its own, nearer one.
+      const fileName =
+        path.relative(process.cwd(), args.path).split(path.sep).join("/") ||
+        args.path;
+      const code = compileModule(ts, fileName, source, { plugins });
+
+      return {
+        contents: ascii(stampBun(code)),
+        loader: args.path.endsWith(".tsx") ? "jsx" : "js",
+      };
+    });
+  },
+});
+
+// Code with every character past ASCII escaped, `\uXXXX`: Bun reads a file
+// stamped `// @bun` (below) as Latin-1, as its own transpiler writes them, so
+// "🏡" would arrive as "ð\u009f\u008f¡". Escaped, a string, identifier or
+// regular expression means what it did. (JSX text doesn't read escapes, but
+// what reaches here is JSX compiled to calls unless a project preserves it.)
+// The source map isn't shifted to match, so columns after an escape on its
+// line are off; lines stay right, which is worth it for text that reads right.
+function ascii(code: string): string {
+  return code.replace(
+    /[^\x00-\x7f]/g,
+    (unit) => `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+// HACK: stamp a `// @bun` pragma at the top of the output to trick Bun into
+// using our inline source map.
+//
+// This relies on undocumented Bun internals and could break on any Bun upgrade.
+// The proper fix would be a real Bun plugin API for handing back a source map.
+//
+// Bun reads the pragma only on the very first line, so it's written into the
+// text rather than onto the first statement, where a leading comment would push
+// it down. The map gains an empty first line to match.
+const MAP = "//# sourceMappingURL=data:application/json;base64,";
+
+function stampBun(code: string): string {
+  const at = code.lastIndexOf(MAP);
+  if (at === -1) {
+    return `// @bun\n${code}`;
+  }
+  const map = JSON.parse(
+    Buffer.from(code.slice(at + MAP.length).trim(), "base64").toString("utf8"),
+  ) as { mappings: string };
+  map.mappings = `;${map.mappings}`;
+  const encoded = Buffer.from(JSON.stringify(map)).toString("base64");
+  return `// @bun\n${code.slice(0, at)}${MAP}${encoded}\n`;
+}