Extract adapter into a separate package

Author: igor10k

.changeset/beige-windows-appear.md

@@ -1,9 +1,5 @@
 ---
-'@remote-dom/core': minor
-'@remote-dom/polyfill': minor
-'@remote-dom/preact': minor
-'@remote-dom/react': minor
-'@remote-dom/signals': minor
+'@remote-dom/compat': major
 ---
 
 Add a `adaptToLegacyRemoteChannel` helper that adapts a Remote DOM `RemoteConnection` object into a `remote-ui` `RemoteChannel`.

examples/kitchen-sink/app/host.tsx

@@ -9,7 +9,7 @@ import {ThreadIframe, ThreadWebWorker} from '@quilted/threads';
 import type {SandboxAPI} from './types.ts';
 import {Button, Modal, Stack, Text, ControlPanel} from './host/components.tsx';
 import {createState} from './host/state.ts';
-import {adaptToLegacyRemoteChannel} from '@remote-dom/core/legacy';
+import {adaptToLegacyRemoteChannel} from '@remote-dom/compat';
 
 // We will put any remote elements we want to render in this root element.
 const uiRoot = document.querySelector('main')!;

examples/kitchen-sink/package.json

@@ -9,6 +9,7 @@
   "dependencies": {
     "@preact/signals": "^1.3.0",
     "@quilted/threads": "^3.0.0",
+    "@remote-dom/compat": "workspace:*",
     "@remote-dom/core": "workspace:*",
     "@remote-dom/preact": "workspace:*",
     "@remote-dom/react": "workspace:*",

examples/kitchen-sink/tsconfig.json

@@ -7,6 +7,7 @@
   },
   "include": ["app"],
   "references": [
+    {"path": "../../packages/compat"},
     {"path": "../../packages/core"},
     {"path": "../../packages/preact"},
     {"path": "../../packages/react"},

packages/compat/README.md

@@ -0,0 +1,36 @@
+# `@remote-dom/compat`
+
+The `@remote-dom/compat` package provides helpers for adapting between Remote DOM and [`remote-ui`, the previous version of this project](https://github.com/Shopify/remote-dom/discussions/267). These utilities are offered to help you transition to Remote DOM, while continuing to support existing code that expects `remote-ui`-style APIs.
+
+## Progressive migration from `remote-ui`’s `RemoteChannel` to Remote DOM’s `RemoteConnection`
+
+The `RemoteChannel` and `RemoteConnection` types from `remote-ui` and Remote DOM serve the same purpose: they describe the minimal interface that a remote environment needs to communicate with a host. In Remote DOM, the `RemoteConnection` type has been enhanced in backwards-incompatible ways, in order to support [method calling](#remote-methods), batched updates, and more.
+
+In `remote-ui`, you typically get a `RemoteChannel` function by accessing the `receiver` property on a `RemoteReceiver`, like this:
+
+```ts
+import {createRemoteReceiver} from '@remote-ui/core';
+
+const receiver = createRemoteReceiver();
+const channel = receiver.receive;
+
+// Do something with the channel, typically by sending it to a remote environment:
+sendChannelToRemoteEnvironment(channel);
+```
+
+You can migrate to use a Remote DOM [`RemoteReceiver`](#remotereceiver), [`DOMRemoteReceiver`](#domremotereceiver), or [`SignalRemoteReceiver`](/packages/signals/README.md#signalremotereceiver) class, while still supporting the `RemoteChannel` API, by using the `adaptToLegacyRemoteChannel()` function:
+
+You can adapt a `RemoteConnection` to a `RemoteChannel` using this library’s `adaptToLegacyRemoteChannel()` function. This function takes a `RemoteConnection` and returns a `RemoteChannel`, which allows you to use a Remote DOM receiver class on the host, even if the remote environment is using `remote-ui`. This same technique works regardless of whether you are using the [`RemoteReceiver`](#remotereceiver), [`DOMRemoteReceiver`](#domremotereceiver), or [`SignalRemoteReceiver`](/packages/signals/README.md#signalremotereceiver) class.
+
+```ts
+import {DOMRemoteReceiver} from '@remote-dom/core/receivers';
+import {adaptToLegacyRemoteChannel} from '@remote-dom/compat';
+
+const receiver = new DOMRemoteReceiver();
+const channel = adaptToLegacyRemoteChannel(receiver.connection);
+
+// Same as before: do something with the channel
+sendChannelToRemoteEnvironment(channel);
+```
+
+If you use `remote-ui`’s React bindings to render your UI on the host, you will also need to update that code to make use of the new Remote DOM versions of those bindings (available for [Preact](/packages/preact/README.md#host) and [React](/packages/react/README.md#host)). With this change made, though, you can now seamlessly support code written with `remote-ui` or Remote DOM, by using the more powerful Remote DOM receiver classes on the host and adapting them for legacy code.

packages/compat/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@remote-dom/compat",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "@remote-dom/registry": "https://registry.npmjs.org"
+  },
+  "version": "1.0.0",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shopify/remote-dom",
+    "directory": "packages/compat"
+  },
+  "exports": {
+    ".": {
+      "types": "./build/typescript/index.d.ts",
+      "quilt:source": "./source/index.ts",
+      "quilt:esnext": "./build/esnext/index.esnext",
+      "import": "./build/esm/index.mjs",
+      "require": "./build/cjs/index.cjs"
+    }
+  },
+  "types": "./build/typescript/index.d.ts",
+  "scripts": {
+    "build": "rollup --config ./rollup.config.js"
+  },
+  "dependencies": {
+    "@remote-dom/core": "workspace:^1.5.2",
+    "@remote-ui/core": "^2.0.0"
+  },
+  "browserslist": [
+    "defaults and not dead"
+  ]
+}

packages/compat/rollup.config.js

@@ -0,0 +1,3 @@
+import {quiltPackage} from '@quilted/rollup/package';
+
+export default quiltPackage({commonjs: true});

packages/core/source/legacy/host.ts packages/compat/source/adapter/host.tspackages/core/source/legacy/host.ts renamed to packages/compat/source/adapter/host.ts

@@ -19,7 +19,7 @@ import type {
   RemoteElementSerialization,
   RemoteConnection,
   RemoteNodeSerialization,
-} from '../types.ts';
+} from '@remote-dom/core';
 import {
   ROOT_ID,
   NODE_TYPE_TEXT,
@@ -28,7 +28,7 @@ import {
   MUTATION_TYPE_REMOVE_CHILD,
   MUTATION_TYPE_UPDATE_PROPERTY,
   MUTATION_TYPE_UPDATE_TEXT,
-} from '../constants.ts';
+} from '@remote-dom/core';
 
 export interface LegacyRemoteChannelElementMap {
   [key: string]: string;
@@ -56,7 +56,7 @@ export interface LegacyRemoteChannelOptions {
  * @example
  * ```tsx
  * import {DOMRemoteReceiver} from '@remote-dom/core/receivers';
- * import {adaptToLegacyRemoteChannel} from '@remote-dom/core/legacy';
+ * import {adaptToLegacyRemoteChannel} from '@remote-dom/compat';
  *
  * const receiver = new DOMRemoteReceiver();
  * const channel = adaptToLegacyRemoteChannel(receiver.connection);

packages/compat/source/index.ts

@@ -0,0 +1 @@
+export {adaptToLegacyRemoteChannel} from './adapter/host';

…es/core/source/legacy/tests/host.test.ts …ages/compat/source/tests/adapter.test.tspackages/core/source/legacy/tests/host.test.ts renamed to packages/compat/source/tests/adapter.test.ts packages/core/source/legacy/tests/host.test.ts renamed to packages/compat/source/tests/adapter.test.ts

@@ -1,8 +1,8 @@
-import '../../polyfill.ts';
+import '@remote-dom/core/polyfill';
 
 import {describe, expect, it, vi, type Mocked} from 'vitest';
 
-import {adaptToLegacyRemoteChannel} from '../../legacy/host.ts';
+import {adaptToLegacyRemoteChannel} from '../adapter/host.ts';
 
 import {
   ACTION_INSERT_CHILD,
@@ -23,9 +23,9 @@ import {
   NODE_TYPE_ELEMENT,
   NODE_TYPE_TEXT,
   ROOT_ID,
-} from '../../constants';
+} from '@remote-dom/core';
 
-import {RemoteReceiver} from '../../receivers/RemoteReceiver.ts';
+import {RemoteReceiver} from '@remote-dom/core/receivers';
 
 describe('adaptToLegacyRemoteChannel()', () => {
   describe('ACTION_MOUNT', () => {