@backtickjs/node-plugin 0.0.0-stage → 0.1.1

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,62 @@
-# Temporary Holding Version
+# @backtickjs/node-plugin
 
-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.
+Runs a Backtick server on Node without a build step. It's a loader, registered with `--import`, 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 Node is your runtime; on Bun, use [`@backtickjs/bun-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/bun-plugin) instead.
+
+## Install
+
+```sh
+npm install @backtickjs/node-plugin typescript
+```
+
+It's a runtime dependency: the server needs it whenever it starts. Requires Node 22.15 or later (it uses `module.registerHooks`) and TypeScript 6.
+
+## Usage
+
+```sh
+node --enable-source-maps --import @backtickjs/node-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
+node --watch --enable-source-maps --import @backtickjs/node-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.
+- 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.
+- Resolves a relative `./Home.js` import to `./Home.ts` or `./Home.tsx` when no `.js` file exists, as TypeScript writes imports of files it compiles.
+- Answers `require` as well as `import`, so a server file starts in a package without `"type": "module"`.
+
+## 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.
+- Pass `--enable-source-maps` for stack traces that point at your `.ts`/`.tsx` lines rather than the compiled output.
+- Files under `node_modules` are left to Node.
+
+## Related
+
+- [`@backtickjs/bun-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/bun-plugin): the same for Bun
+- [`@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/hooks.d.ts

@@ -0,0 +1,3 @@
+import { type LoadHookSync, type ResolveHookSync } from "node:module";
+export declare const resolve: ResolveHookSync;
+export declare const load: LoadHookSync;

package/dist/hooks.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { createRequire, } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileModule, pluginsFrom } from "@backtickjs/compiler";
+import ts from "typescript";
+// Node's module hooks, registered by `index.ts`. The framework's compile steps
+// are read once, from the project's `package.json`.
+const packageJson = path.join(process.cwd(), "package.json");
+const plugins = pluginsFrom(readFileSync(packageJson, "utf8"), createRequire(packageJson));
+// The project's own TypeScript, not what it installed.
+const compiled = (url) => url.startsWith("file:") &&
+    /\.tsx?$/.test(url) &&
+    !url.includes("/node_modules/");
+// `./Home.js` for `./Home.tsx`, as TypeScript writes an import of a file it
+// compiles: tried as written first, then as the source it stands for.
+export const resolve = (specifier, context, nextResolve) => {
+    try {
+        return nextResolve(specifier, context);
+    }
+    catch (error) {
+        const relative = specifier.startsWith("./") || specifier.startsWith("../");
+        if (!relative || !specifier.endsWith(".js")) {
+            throw error;
+        }
+        for (const extension of [".ts", ".tsx"]) {
+            try {
+                return nextResolve(specifier.slice(0, -3) + extension, context);
+            }
+            catch { }
+        }
+        throw error;
+    }
+};
+export const load = (url, context, nextLoad) => {
+    if (!compiled(url)) {
+        return nextLoad(url, context);
+    }
+    const file = fileURLToPath(url);
+    const fileName = path.relative(process.cwd(), file).split(path.sep).join("/") || file;
+    const source = compileModule(ts, fileName, readFileSync(file, "utf8"), {
+        plugins,
+    });
+    return { format: "module", source, shortCircuit: true };
+};
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EACL,aAAa,GAGd,MAAM,aAAa,CAAC;AACrB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,+EAA+E;AAC/E,oDAAoD;AACpD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,cAAc,CAAC,CAAC;AAC7D,MAAM,OAAO,GAAG,WAAW,CACzB,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,EACjC,aAAa,CAAC,WAAW,CAAC,CAC3B,CAAC;AAEF,uDAAuD;AACvD,MAAM,QAAQ,GAAG,CAAC,GAAW,EAAE,EAAE,CAC/B,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC;IACvB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;IACnB,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;AAElC,4EAA4E;AAC5E,sEAAsE;AACtE,MAAM,CAAC,MAAM,OAAO,GAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE;IAC1E,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC3E,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5C,MAAM,KAAK,CAAC;QACd,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,OAAO,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,OAAO,CAAC,CAAC;YAClE,CAAC;YAAC,MAAM,CAAC,CAAA,CAAC;QACZ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,IAAI,GAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;IAC3D,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,OAAO,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IACD,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IACvE,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;QACrE,OAAO;KACR,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AAC1D,CAAC,CAAC"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,23 @@
+import { registerHooks } from "node:module";
+import { load, resolve } from "./hooks.js";
+/**
+ * Use it from the command line, as Node's `--import`:
+ *
+ * ```sh
+ * node --import @backtickjs/node-plugin ./server/index.tsx
+ * ```
+ *
+ * TypeScript and JSX files outside `node_modules` are compiled as they load,
+ * their `cs` scripts with them. The framework's compile steps are the
+ * project's, named in its `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/react/plugin"] }
+ * ```
+ */
+//
+// The hooks run on this thread, synchronously, so they answer `require` as well
+// as `import`: an app's package.json has no `"type": "module"`, so Node starts
+// a server file as CommonJS before it sees the `import`s.
+registerHooks({ resolve, load });
+//# 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,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,0DAA0D;AAC1D,aAAa,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@backtickjs/node-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Runs a Backtick server on Node without a build step, compiling its files and client scripts as they load",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "server-driven-ui",
+    "server-components",
+    "node",
+    "loader",
+    "module-hooks"
+  ],
+  "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/node-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.1"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.3",
+    "@backtickjs/core": "0.1.1"
+  },
+  "engines": {
+    "node": ">=22.15"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "node --enable-source-maps --import ./dist/index.js --test \"test/**/*.test.ts\"",
+    "format": "prettier --write --ignore-unknown .",
+    "format:check": "prettier --check --ignore-unknown .",
+    "clean": "rm -rf node_modules dist .turbo"
+  }
 }

package/src/hooks.ts

@@ -0,0 +1,56 @@
+import { readFileSync } from "node:fs";
+import {
+  createRequire,
+  type LoadHookSync,
+  type ResolveHookSync,
+} from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { compileModule, pluginsFrom } from "@backtickjs/compiler";
+import ts from "typescript";
+
+// Node's module hooks, registered by `index.ts`. The framework's compile steps
+// are read once, from the project's `package.json`.
+const packageJson = path.join(process.cwd(), "package.json");
+const plugins = pluginsFrom(
+  readFileSync(packageJson, "utf8"),
+  createRequire(packageJson),
+);
+
+// The project's own TypeScript, not what it installed.
+const compiled = (url: string) =>
+  url.startsWith("file:") &&
+  /\.tsx?$/.test(url) &&
+  !url.includes("/node_modules/");
+
+// `./Home.js` for `./Home.tsx`, as TypeScript writes an import of a file it
+// compiles: tried as written first, then as the source it stands for.
+export const resolve: ResolveHookSync = (specifier, context, nextResolve) => {
+  try {
+    return nextResolve(specifier, context);
+  } catch (error) {
+    const relative = specifier.startsWith("./") || specifier.startsWith("../");
+    if (!relative || !specifier.endsWith(".js")) {
+      throw error;
+    }
+    for (const extension of [".ts", ".tsx"]) {
+      try {
+        return nextResolve(specifier.slice(0, -3) + extension, context);
+      } catch {}
+    }
+    throw error;
+  }
+};
+
+export const load: LoadHookSync = (url, context, nextLoad) => {
+  if (!compiled(url)) {
+    return nextLoad(url, context);
+  }
+  const file = fileURLToPath(url);
+  const fileName =
+    path.relative(process.cwd(), file).split(path.sep).join("/") || file;
+  const source = compileModule(ts, fileName, readFileSync(file, "utf8"), {
+    plugins,
+  });
+  return { format: "module", source, shortCircuit: true };
+};

package/src/index.ts

@@ -0,0 +1,23 @@
+import { registerHooks } from "node:module";
+import { load, resolve } from "./hooks.js";
+
+/**
+ * Use it from the command line, as Node's `--import`:
+ *
+ * ```sh
+ * node --import @backtickjs/node-plugin ./server/index.tsx
+ * ```
+ *
+ * TypeScript and JSX files outside `node_modules` are compiled as they load,
+ * their `cs` scripts with them. The framework's compile steps are the
+ * project's, named in its `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/react/plugin"] }
+ * ```
+ */
+//
+// The hooks run on this thread, synchronously, so they answer `require` as well
+// as `import`: an app's package.json has no `"type": "module"`, so Node starts
+// a server file as CommonJS before it sees the `import`s.
+registerHooks({ resolve, load });