@backtickjs/tspatch-plugin 0.0.0-stage → 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

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @backtickjs/tspatch-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.
+Compiles `cs` client scripts when you build your server ahead of time. It's a [ts-patch](https://github.com/nonara/ts-patch) transformer: build with `tspc` and the output is plain JavaScript, which runs on `node`, Bun or a serverless platform with no loader. To compile a server's files as they load instead, with no build step, use [`@backtickjs/node-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/node-plugin) or [`@backtickjs/bun-plugin`](https://github.com/backtickjs/backtick/tree/main/packages/bun-plugin). Backtick's own adapters are built with it.
+
+## Usage
+
+Requires ts-patch 4 and TypeScript 6. Add the transformer to `tsconfig.json`, and name your framework's compile steps in the `package.json` beside it:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [{ "transform": "@backtickjs/tspatch-plugin" }]
+  }
+}
+```
+
+```json
+{
+  "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] },
+  "scripts": {
+    "build": "tspc -b --noCheck",
+    "typecheck": "backtick-tsc --noEmit"
+  }
+}
+```
+
+Build with `tspc` (from ts-patch) in place of `tsc`; plain `tsc` ignores the transformer and leaves scripts uncompiled. Backtick's adapters build with `--noCheck` and type-check separately with [`backtick-tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc), which checks inside scripts. A script the compiler refuses is reported as a build error.
+
+Source maps name a script's file as `<package name>/<path from the tsconfig directory>`, so they are the same on every machine.
+
+## Related
+
+- [`@backtickjs/tsc`](https://github.com/backtickjs/backtick/tree/main/packages/tsc): type-checks scripts and writes their declarations
+- [Documentation](https://backtickjs.com/docs)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { PluginConfig, TransformerExtras } from "ts-patch";
+import type ts from "typescript";
+/**
+ * Use it from a `tsconfig.json`:
+ *
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "plugins": [{ "transform": "@backtickjs/tspatch-plugin" }]
+ *   }
+ * }
+ * ```
+ *
+ * and compile with `tspc` (from `ts-patch`) instead of `tsc`. The framework's
+ * compile steps are the project's, named in its `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] }
+ * ```
+ */
+export default function transformer(program: ts.Program, _config: PluginConfig, { ts, addDiagnostic }: TransformerExtras): ts.TransformerFactory<ts.SourceFile>;

package/dist/index.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pluginsFrom, transform } from "@backtickjs/compiler";
+/**
+ * Use it from a `tsconfig.json`:
+ *
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "plugins": [{ "transform": "@backtickjs/tspatch-plugin" }]
+ *   }
+ * }
+ * ```
+ *
+ * and compile with `tspc` (from `ts-patch`) instead of `tsc`. The framework's
+ * compile steps are the project's, named in its `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] }
+ * ```
+ */
+export default function transformer(program, _config, { ts, addDiagnostic }) {
+    // A script's map names its file as its package does, `@scope/name/src/…`, as
+    // webpack's `webpack://<package name>/…` does: the same on every machine, and
+    // distinct from another package's in a bundle's map. The package is the one
+    // whose `tsconfig.json` this builds.
+    const root = path.posix.dirname(program.getCompilerOptions().configFilePath);
+    const packageJson = readFileSync(path.join(root, "package.json"), "utf8");
+    const { name } = JSON.parse(packageJson);
+    // Loaded as the project resolves them, at once, as a transformer is.
+    const plugins = pluginsFrom(packageJson, createRequire(path.resolve(root, "package.json")));
+    return transform(ts, (diagnostic) => {
+        addDiagnostic(diagnostic);
+    }, 
+    // TypeScript's file names use `/` on every platform.
+    {
+        sourceName: (fileName) => path.posix.join(name, path.posix.relative(root, fileName)),
+        plugins,
+    });
+}
+//# 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,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAI9D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,OAAO,UAAU,WAAW,CACjC,OAAmB,EACnB,OAAqB,EACrB,EAAE,EAAE,EAAE,aAAa,EAAqB;IAExC,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,qCAAqC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAC7B,OAAO,CAAC,kBAAkB,EAAE,CAAC,cAAwB,CACtD,CAAC;IACF,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1E,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAqB,CAAC;IAC7D,qEAAqE;IACrE,MAAM,OAAO,GAAG,WAAW,CACzB,WAAW,EACX,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAClD,CAAC;IACF,OAAO,SAAS,CACd,EAAE,EACF,CAAC,UAAU,EAAE,EAAE;QACb,aAAa,CAAC,UAAU,CAAC,CAAC;IAC5B,CAAC;IACD,qDAAqD;IACrD;QACE,UAAU,EAAE,CAAC,QAAQ,EAAE,EAAE,CACvB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC5D,OAAO;KACR,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@backtickjs/tspatch-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Compiles Backtick client scripts when you build your server ahead of time with ts-patch's tspc",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "server-driven-ui",
+    "server-components",
+    "ts-patch",
+    "tspc",
+    "typescript",
+    "transformer"
+  ],
+  "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/tspatch-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": {
+    "ts-patch": "^4.0.1",
+    "typescript": "^6.0.3"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2",
+    "ts-patch": "^4.0.1",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "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,57 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pluginsFrom, transform } from "@backtickjs/compiler";
+import type { PluginConfig, TransformerExtras } from "ts-patch";
+import type ts from "typescript";
+
+/**
+ * Use it from a `tsconfig.json`:
+ *
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "plugins": [{ "transform": "@backtickjs/tspatch-plugin" }]
+ *   }
+ * }
+ * ```
+ *
+ * and compile with `tspc` (from `ts-patch`) instead of `tsc`. The framework's
+ * compile steps are the project's, named in its `package.json`:
+ *
+ * ```json
+ * "backtick": { "plugins": ["@backtickjs/solid-js/plugin"] }
+ * ```
+ */
+export default function transformer(
+  program: ts.Program,
+  _config: PluginConfig,
+  { ts, addDiagnostic }: TransformerExtras,
+): ts.TransformerFactory<ts.SourceFile> {
+  // A script's map names its file as its package does, `@scope/name/src/…`, as
+  // webpack's `webpack://<package name>/…` does: the same on every machine, and
+  // distinct from another package's in a bundle's map. The package is the one
+  // whose `tsconfig.json` this builds.
+  const root = path.posix.dirname(
+    program.getCompilerOptions().configFilePath as string,
+  );
+  const packageJson = readFileSync(path.join(root, "package.json"), "utf8");
+  const { name } = JSON.parse(packageJson) as { name: string };
+  // Loaded as the project resolves them, at once, as a transformer is.
+  const plugins = pluginsFrom(
+    packageJson,
+    createRequire(path.resolve(root, "package.json")),
+  );
+  return transform(
+    ts,
+    (diagnostic) => {
+      addDiagnostic(diagnostic);
+    },
+    // TypeScript's file names use `/` on every platform.
+    {
+      sourceName: (fileName) =>
+        path.posix.join(name, path.posix.relative(root, fileName)),
+      plugins,
+    },
+  );
+}