@evolu/react 10.4.0 → 11.0.0-next.0

package/README.md

@@ -1,6 +1,6 @@
 # Evolu for React
 
-[Evolu](https://github.com/evoluhq/evolu) for [React](https://react.dev).
+This package provides universal [React](https://react.dev) functionality for Evolu that works across all React environments (excluding React Native and React Web, which have their own packages).
 
 ## Documentation
 
@@ -12,4 +12,4 @@ The Evolu community is on [GitHub Discussions](https://github.com/evoluhq/evolu/
 
 To chat with other community members, you can join the [Evolu Discord](https://discord.gg/2J8yyyyxtZ).
 
-[![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/evoluhq.svg?style=social&label=Follow%20%40evoluhq)](https://twitter.com/evoluhq)
+[![X](https://img.shields.io/twitter/url/https/x.com/evoluhq.svg?style=social&label=Follow%20%40evoluhq)](https://x.com/evoluhq)

package/dist/src/Task.d.ts

@@ -0,0 +1,42 @@
+import { type Run } from "@evolu/common";
+import { type ReactNode } from "react";
+/**
+ * Creates typed React Context and hook for {@link Run}.
+ *
+ * The `run` argument is used to infer the deps type for the returned API.
+ *
+ * `useRun` throws when the provider is missing.
+ *
+ * ### Example
+ *
+ * ```tsx
+ * const run = createRun(createEvoluDeps());
+ * const { RunContext, useRun } = createRunBinding(run);
+ *
+ * <RunContext value={run}>
+ *   <App />
+ * </RunContext>;
+ *
+ * // In a component
+ * const run = useRun();
+ * ```
+ *
+ * ### Testing
+ *
+ * ```tsx
+ * const testRun = testCreateRun({ api: testApi });
+ * const { RunContext } = createRunBinding(testRun);
+ *
+ * <RunContext value={testRun}>
+ *   <MyComponent />
+ * </RunContext>;
+ * ```
+ */
+export declare const createRunBinding: <D>(run: Run<D>) => {
+    readonly RunContext: React.FC<{
+        readonly value: Run<D>;
+        readonly children?: ReactNode;
+    }>;
+    readonly useRun: () => Run<D>;
+};
+//# sourceMappingURL=Task.d.ts.map

package/dist/src/Task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../src/Task.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAU,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAEhC,KAAK,GAAG,CAAC,CAAC,CAAC,KACV;IACD,QAAQ,CAAC,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;KAC/B,CAAC,CAAC;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC;CAY/B,CAAC"}

package/dist/src/Task.js

@@ -0,0 +1,48 @@
+"use client";
+import { assert } from "@evolu/common";
+import { createContext, use } from "react";
+/**
+ * Creates typed React Context and hook for {@link Run}.
+ *
+ * The `run` argument is used to infer the deps type for the returned API.
+ *
+ * `useRun` throws when the provider is missing.
+ *
+ * ### Example
+ *
+ * ```tsx
+ * const run = createRun(createEvoluDeps());
+ * const { RunContext, useRun } = createRunBinding(run);
+ *
+ * <RunContext value={run}>
+ *   <App />
+ * </RunContext>;
+ *
+ * // In a component
+ * const run = useRun();
+ * ```
+ *
+ * ### Testing
+ *
+ * ```tsx
+ * const testRun = testCreateRun({ api: testApi });
+ * const { RunContext } = createRunBinding(testRun);
+ *
+ * <RunContext value={testRun}>
+ *   <MyComponent />
+ * </RunContext>;
+ * ```
+ */
+export const createRunBinding = (
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+run) => {
+    const RunContext = createContext(null);
+    return {
+        RunContext,
+        useRun: () => {
+            const run = use(RunContext);
+            assert(run, "RunContext is missing.");
+            return run;
+        },
+    };
+};

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./local-first/createEvoluBinding.js";
+export * from "./local-first/useIsSsr.js";
+export * from "./Task.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,WAAW,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,3 @@
+export * from "./local-first/createEvoluBinding.js";
+export * from "./local-first/useIsSsr.js";
+export * from "./Task.js";

package/dist/src/local-first/createEvoluBinding.d.ts

@@ -0,0 +1,64 @@
+import type { Evolu, EvoluSchema, Queries, QueriesToQueryRows, QueriesToQueryRowsPromises, Query, QueryRows, Row } from "@evolu/common/local-first";
+import { type ReactNode } from "react";
+export interface ReactBinding<S extends EvoluSchema = EvoluSchema> {
+    /** Provides {@link Evolu} to React descendants consumed via `useEvolu`. */
+    readonly EvoluContext: React.FC<{
+        readonly value: Evolu<S>;
+        readonly children?: ReactNode;
+    }>;
+    /** Returns the current {@link Evolu} instance from `EvoluContext`. */
+    readonly useEvolu: () => Evolu<S>;
+    /**
+     * Load and subscribe to the Query, and return an object with `rows` and `row`
+     * properties that are automatically updated when data changes.
+     *
+     * Note that `useQuery` uses React Suspense. It means every usage of
+     * `useQuery` blocks rendering until loading is completed. To avoid loading
+     * waterfall with more queries, use `useQueries`.
+     *
+     * The `promise` option allows preloading queries before rendering, which can
+     * be useful for complex queries that might take noticeable time even with
+     * local data. However, this is rarely needed as local queries are typically
+     * fast.
+     */
+    readonly useQuery: <R extends Row>(query: Query<S, R>, options?: Partial<{
+        /** Without subscribing to changes. */
+        readonly once: boolean;
+        /** Reuse existing promise instead of loading so query will not suspense. */
+        readonly promise: Promise<QueryRows<R>>;
+    }>) => QueryRows<R>;
+    /**
+     * The same as `useQuery`, but for many queries.
+     *
+     * The number of queries must remain stable across renders.
+     */
+    readonly useQueries: <Q extends Queries<S>, OQ extends Queries<S>>(queries: [...Q], options?: Partial<{
+        /** Queries that should be only loaded, not subscribed to. */
+        readonly once: [...OQ];
+        /** Reuse existing promises instead of loading so query will not suspense. */
+        readonly promises: [
+            ...QueriesToQueryRowsPromises<Q>,
+            ...QueriesToQueryRowsPromises<OQ>
+        ];
+    }>) => [...QueriesToQueryRows<Q>, ...QueriesToQueryRows<OQ>];
+    /** Subscribe to {@link Query} {@link QueryRows} changes. */
+    readonly useQuerySubscription: <R extends Row>(query: Query<S, R>, options?: Partial<{
+        /**
+         * Only subscribe and get the current value once. Subscribed query will
+         * not invoke React Suspense after a mutation.
+         */
+        readonly once: boolean;
+    }>) => QueryRows<R>;
+    /** Calls {@link Evolu.useOwner} on the current {@link Evolu} instance. */
+    readonly useOwner: (owner: Parameters<Evolu<S>["useOwner"]>[0], transports?: Parameters<Evolu<S>["useOwner"]>[1]) => ReturnType<Evolu<S>["useOwner"]>;
+}
+/**
+ * Creates a React binding for a specific {@link EvoluSchema}.
+ *
+ * The created binding contains the context component and all hooks needed by
+ * React components using an {@link Evolu} instance created from that schema.
+ *
+ * TODO: Example from playground example.
+ */
+export declare const createEvoluBinding: <S extends EvoluSchema>(schema: S) => ReactBinding<S>;
+//# sourceMappingURL=createEvoluBinding.d.ts.map

package/dist/src/local-first/createEvoluBinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createEvoluBinding.d.ts","sourceRoot":"","sources":["../../../src/local-first/createEvoluBinding.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,KAAK,EACL,WAAW,EACX,OAAO,EACP,kBAAkB,EAClB,0BAA0B,EAC1B,KAAK,EACL,SAAS,EACT,GAAG,EACJ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAGf,MAAM,WAAW,YAAY,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW;IAC/D,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC;QAC9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;KAC/B,CAAC,CAAC;IAEH,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;IAElC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,GAAG,EAC/B,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAChB,sCAAsC;QACtC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAEvB,4EAA4E;QAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;KACzC,CAAC,KACC,SAAS,CAAC,CAAC,CAAC,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,SAAS,OAAO,CAAC,CAAC,CAAC,EAC/D,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,EACf,OAAO,CAAC,EAAE,OAAO,CAAC;QAChB,6DAA6D;QAC7D,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QAEvB,6EAA6E;QAC7E,QAAQ,CAAC,QAAQ,EAAE;YACjB,GAAG,0BAA0B,CAAC,CAAC,CAAC;YAChC,GAAG,0BAA0B,CAAC,EAAE,CAAC;SAClC,CAAC;KACH,CAAC,KACC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,EAAE,GAAG,kBAAkB,CAAC,EAAE,CAAC,CAAC,CAAC;IAE3D,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC,SAAS,GAAG,EAC3C,KAAK,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAChB;;;WAGG;QACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;KACxB,CAAC,KACC,SAAS,CAAC,CAAC,CAAC,CAAC;IAElB,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,EAC1C,UAAU,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,KAC7C,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;CACvC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,WAAW,EAEtD,QAAQ,CAAC,KACR,YAAY,CAAC,CAAC,CAiGhB,CAAC"}

package/dist/src/local-first/createEvoluBinding.js

@@ -0,0 +1,76 @@
+"use client";
+import { assert, emptyArray, lazyVoid } from "@evolu/common";
+import { createContext, use, useEffect, useMemo, useRef, useSyncExternalStore, } from "react";
+import { useIsSsr } from "./useIsSsr.js";
+/**
+ * Creates a React binding for a specific {@link EvoluSchema}.
+ *
+ * The created binding contains the context component and all hooks needed by
+ * React components using an {@link Evolu} instance created from that schema.
+ *
+ * TODO: Example from playground example.
+ */
+export const createEvoluBinding = (
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+schema) => {
+    const EvoluContext = createContext(null);
+    const useEvolu = () => {
+        const evolu = use(EvoluContext);
+        assert(evolu, "EvoluContext is missing.");
+        return evolu;
+    };
+    const useQuerySubscription = (query, options = {}) => {
+        const evolu = useEvolu();
+        const { once } = useRef(options).current;
+        if (once) {
+            /* eslint-disable react-hooks/rules-of-hooks */
+            useEffect(() => evolu.subscribeQuery(query)(lazyVoid), [evolu, query]);
+            return evolu.getQueryRows(query);
+        }
+        return useSyncExternalStore(useMemo(() => evolu.subscribeQuery(query), [evolu, query]), useMemo(() => () => evolu.getQueryRows(query), [evolu, query]), () => emptyArray);
+    };
+    const useQuery = (query, options = {}) => {
+        const evolu = useEvolu();
+        const isSSR = useIsSsr();
+        if (isSSR) {
+            if (!options.promise)
+                void evolu.loadQuery(query);
+        }
+        else {
+            use(options.promise ?? evolu.loadQuery(query));
+        }
+        return useQuerySubscription(query, options);
+    };
+    const useQueries = (queries, options = {}) => {
+        const evolu = useEvolu();
+        const once = useRef(options).current.once;
+        const allQueries = once ? queries.concat(once) : queries;
+        const wasSSR = useIsSsr();
+        if (wasSSR) {
+            if (!options.promises)
+                void evolu.loadQueries(allQueries);
+        }
+        else {
+            if (options.promises)
+                options.promises.map(use);
+            else
+                evolu.loadQueries(allQueries).map(use);
+        }
+        return allQueries.map((query, index) => 
+        // Safe until the number of queries is stable.
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        useQuerySubscription(query, { once: index > queries.length - 1 }));
+    };
+    const useOwner = (owner, transports) => {
+        const evolu = useEvolu();
+        return evolu.useOwner(owner, transports);
+    };
+    return {
+        EvoluContext,
+        useEvolu,
+        useQuery,
+        useQueries,
+        useQuerySubscription,
+        useOwner,
+    };
+};

package/dist/src/local-first/useIsSsr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsSsr.d.ts","sourceRoot":"","sources":["../../../src/local-first/useIsSsr.ts"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAO,OAE+B,CAAC"}

package/dist/{useIsSsr.js → src/local-first/useIsSsr.js}

@@ -1,4 +1,4 @@
-import { constFalse, constTrue } from "@evolu/common";
+import { lazyFalse, lazyTrue } from "@evolu/common";
 import { useSyncExternalStore } from "react";
 // eslint-disable-next-line @typescript-eslint/no-empty-function
 const emptySubscribe = () => () => { };
@@ -7,7 +7,6 @@ const emptySubscribe = () => () => { };
  *
  * @see https://kurtextrem.de/posts/react-uses-hydration
  */
-export const useIsSsr = () => {
-    // TODO: Consider useDeferredValue(isSSRSync);
-    return useSyncExternalStore(emptySubscribe, constFalse, constTrue);
-};
+export const useIsSsr = () => 
+// TODO: Consider useDeferredValue(isSSRSync);
+useSyncExternalStore(emptySubscribe, lazyFalse, lazyTrue);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evolu/react",
-  "version": "10.4.0",
+  "version": "11.0.0-next.0",
   "description": "Evolu for React",
   "keywords": [
     "evolu",
@@ -15,44 +15,42 @@
   },
   "homepage": "https://evolu.dev",
   "type": "module",
-  "types": "./dist/index.d.ts",
+  "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "browser": "./dist/index.js",
-      "react-native": "./dist/index.js"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "browser": "./dist/src/index.js",
+      "react-native": "./dist/src/index.js"
     }
   },
   "files": [
-    "dist/**",
+    "dist/src/**",
     "src/**",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "prepack": "npm run build",
+    "format": "prettier --write \"src/*.{ts,tsx,md}\""
+  },
   "devDependencies": {
-    "@types/react": "~19.1.13",
-    "@types/react-dom": "~19.1.9",
-    "react": "19.1.0",
-    "typescript": "^5.9.2",
-    "vitest": "^4.0.4",
-    "@evolu/common": "7.4.0",
-    "@evolu/tsconfig": "0.0.2"
+    "@evolu/common": "8.0.0-next.0",
+    "@evolu/typescript-config": "*",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@evolu/common": "^7.4.0",
+    "@evolu/common": "^8.0.0-next.0",
     "react": ">=19"
   },
   "publishConfig": {
     "access": "public"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=24.0.0"
   },
-  "sideEffects": [],
-  "scripts": {
-    "dev": "tsc --watch",
-    "build": "rimraf dist && tsc",
-    "clean": "rimraf .turbo node_modules dist",
-    "format": "prettier --write \"src/*.{ts,tsx,md}\""
-  }
-}
+  "sideEffects": false
+}

package/src/Task.tsx

@@ -0,0 +1,58 @@
+"use client";
+
+import { assert, type Run } from "@evolu/common";
+import { createContext, use, type ReactNode } from "react";
+
+/**
+ * Creates typed React Context and hook for {@link Run}.
+ *
+ * The `run` argument is used to infer the deps type for the returned API.
+ *
+ * `useRun` throws when the provider is missing.
+ *
+ * ### Example
+ *
+ * ```tsx
+ * const run = createRun(createEvoluDeps());
+ * const { RunContext, useRun } = createRunBinding(run);
+ *
+ * <RunContext value={run}>
+ *   <App />
+ * </RunContext>;
+ *
+ * // In a component
+ * const run = useRun();
+ * ```
+ *
+ * ### Testing
+ *
+ * ```tsx
+ * const testRun = testCreateRun({ api: testApi });
+ * const { RunContext } = createRunBinding(testRun);
+ *
+ * <RunContext value={testRun}>
+ *   <MyComponent />
+ * </RunContext>;
+ * ```
+ */
+export const createRunBinding = <D,>(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  run: Run<D>,
+): {
+  readonly RunContext: React.FC<{
+    readonly value: Run<D>;
+    readonly children?: ReactNode;
+  }>;
+  readonly useRun: () => Run<D>;
+} => {
+  const RunContext = createContext<Run<D> | null>(null);
+
+  return {
+    RunContext,
+    useRun: () => {
+      const run = use(RunContext);
+      assert(run, "RunContext is missing.");
+      return run;
+    },
+  };
+};

package/src/index.ts

@@ -1,11 +1,3 @@
-export * from "./createUseEvolu.js";
-export * from "./EvoluContext.js";
-export * from "./EvoluProvider.js";
-export * from "./useEvolu.js";
-export * from "./useEvoluError.js";
-export * from "./useOwner.js";
-export * from "./useQueries.js";
-export * from "./useQuery.js";
-export * from "./useQuerySubscription.js";
-// export * from "./useSyncState.js"; TODO: Update it for the owner-api
-export * from "./useIsSsr.js";
+export * from "./local-first/createEvoluBinding.js";
+export * from "./local-first/useIsSsr.js";
+export * from "./Task.js";

package/src/local-first/createEvoluBinding.tsx

@@ -0,0 +1,205 @@
+"use client";
+
+import { assert, emptyArray, lazyVoid } from "@evolu/common";
+import type {
+  Evolu,
+  EvoluSchema,
+  Queries,
+  QueriesToQueryRows,
+  QueriesToQueryRowsPromises,
+  Query,
+  QueryRows,
+  Row,
+} from "@evolu/common/local-first";
+import {
+  createContext,
+  use,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { useIsSsr } from "./useIsSsr.js";
+
+export interface ReactBinding<S extends EvoluSchema = EvoluSchema> {
+  /** Provides {@link Evolu} to React descendants consumed via `useEvolu`. */
+  readonly EvoluContext: React.FC<{
+    readonly value: Evolu<S>;
+    readonly children?: ReactNode;
+  }>;
+
+  /** Returns the current {@link Evolu} instance from `EvoluContext`. */
+  readonly useEvolu: () => Evolu<S>;
+
+  /**
+   * Load and subscribe to the Query, and return an object with `rows` and `row`
+   * properties that are automatically updated when data changes.
+   *
+   * Note that `useQuery` uses React Suspense. It means every usage of
+   * `useQuery` blocks rendering until loading is completed. To avoid loading
+   * waterfall with more queries, use `useQueries`.
+   *
+   * The `promise` option allows preloading queries before rendering, which can
+   * be useful for complex queries that might take noticeable time even with
+   * local data. However, this is rarely needed as local queries are typically
+   * fast.
+   */
+  readonly useQuery: <R extends Row>(
+    query: Query<S, R>,
+    options?: Partial<{
+      /** Without subscribing to changes. */
+      readonly once: boolean;
+
+      /** Reuse existing promise instead of loading so query will not suspense. */
+      readonly promise: Promise<QueryRows<R>>;
+    }>,
+  ) => QueryRows<R>;
+
+  /**
+   * The same as `useQuery`, but for many queries.
+   *
+   * The number of queries must remain stable across renders.
+   */
+  readonly useQueries: <Q extends Queries<S>, OQ extends Queries<S>>(
+    queries: [...Q],
+    options?: Partial<{
+      /** Queries that should be only loaded, not subscribed to. */
+      readonly once: [...OQ];
+
+      /** Reuse existing promises instead of loading so query will not suspense. */
+      readonly promises: [
+        ...QueriesToQueryRowsPromises<Q>,
+        ...QueriesToQueryRowsPromises<OQ>,
+      ];
+    }>,
+  ) => [...QueriesToQueryRows<Q>, ...QueriesToQueryRows<OQ>];
+
+  /** Subscribe to {@link Query} {@link QueryRows} changes. */
+  readonly useQuerySubscription: <R extends Row>(
+    query: Query<S, R>,
+    options?: Partial<{
+      /**
+       * Only subscribe and get the current value once. Subscribed query will
+       * not invoke React Suspense after a mutation.
+       */
+      readonly once: boolean;
+    }>,
+  ) => QueryRows<R>;
+
+  /** Calls {@link Evolu.useOwner} on the current {@link Evolu} instance. */
+  readonly useOwner: (
+    owner: Parameters<Evolu<S>["useOwner"]>[0],
+    transports?: Parameters<Evolu<S>["useOwner"]>[1],
+  ) => ReturnType<Evolu<S>["useOwner"]>;
+}
+
+/**
+ * Creates a React binding for a specific {@link EvoluSchema}.
+ *
+ * The created binding contains the context component and all hooks needed by
+ * React components using an {@link Evolu} instance created from that schema.
+ *
+ * TODO: Example from playground example.
+ */
+export const createEvoluBinding = <S extends EvoluSchema>(
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  schema: S,
+): ReactBinding<S> => {
+  const EvoluContext = createContext<Evolu<S> | null>(null);
+
+  const useEvolu = (): Evolu<S> => {
+    const evolu = use(EvoluContext);
+    assert(evolu, "EvoluContext is missing.");
+    return evolu;
+  };
+
+  const useQuerySubscription = <R extends Row>(
+    query: Query<S, R>,
+    options: Partial<{
+      readonly once: boolean;
+    }> = {},
+  ): QueryRows<R> => {
+    const evolu = useEvolu();
+    const { once } = useRef(options).current;
+
+    if (once) {
+      /* eslint-disable react-hooks/rules-of-hooks */
+      useEffect(() => evolu.subscribeQuery(query)(lazyVoid), [evolu, query]);
+      return evolu.getQueryRows(query);
+    }
+
+    return useSyncExternalStore(
+      useMemo(() => evolu.subscribeQuery(query), [evolu, query]),
+      useMemo(() => () => evolu.getQueryRows(query), [evolu, query]),
+      () => emptyArray as QueryRows<R>,
+      /* eslint-enable react-hooks/rules-of-hooks */
+    );
+  };
+
+  const useQuery = <R extends Row>(
+    query: Query<S, R>,
+    options: Partial<{
+      readonly once: boolean;
+      readonly promise: Promise<QueryRows<R>>;
+    }> = {},
+  ): QueryRows<R> => {
+    const evolu = useEvolu();
+    const isSSR = useIsSsr();
+
+    if (isSSR) {
+      if (!options.promise) void evolu.loadQuery(query);
+    } else {
+      use(options.promise ?? evolu.loadQuery(query));
+    }
+
+    return useQuerySubscription(query, options);
+  };
+
+  const useQueries = <Q extends Queries<S>, OQ extends Queries<S>>(
+    queries: [...Q],
+    options: Partial<{
+      readonly once: [...OQ];
+      readonly promises: [
+        ...QueriesToQueryRowsPromises<Q>,
+        ...QueriesToQueryRowsPromises<OQ>,
+      ];
+    }> = {},
+  ): [...QueriesToQueryRows<Q>, ...QueriesToQueryRows<OQ>] => {
+    const evolu = useEvolu();
+    const once = useRef(options).current.once;
+    const allQueries = once ? queries.concat(once) : queries;
+
+    const wasSSR = useIsSsr();
+    if (wasSSR) {
+      if (!options.promises) void evolu.loadQueries(allQueries);
+    } else {
+      if (options.promises) options.promises.map(use);
+      else evolu.loadQueries(allQueries).map(use);
+    }
+
+    return allQueries.map((query, index) =>
+      // Safe until the number of queries is stable.
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      useQuerySubscription(query, { once: index > queries.length - 1 }),
+    ) as never;
+  };
+
+  const useOwner = (
+    owner: Parameters<Evolu<S>["useOwner"]>[0],
+    transports?: Parameters<Evolu<S>["useOwner"]>[1],
+  ): ReturnType<Evolu<S>["useOwner"]> => {
+    const evolu = useEvolu();
+
+    return evolu.useOwner(owner, transports);
+  };
+
+  return {
+    EvoluContext,
+    useEvolu,
+    useQuery,
+    useQueries,
+    useQuerySubscription,
+    useOwner,
+  };
+};

package/src/{useIsSsr.ts → local-first/useIsSsr.ts}

@@ -1,4 +1,4 @@
-import { constFalse, constTrue } from "@evolu/common";
+import { lazyFalse, lazyTrue } from "@evolu/common";
 import { useSyncExternalStore } from "react";
 
 // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -9,7 +9,6 @@ const emptySubscribe = () => () => {};
  *
  * @see https://kurtextrem.de/posts/react-uses-hydration
  */
-export const useIsSsr = (): boolean => {
+export const useIsSsr = (): boolean =>
   // TODO: Consider useDeferredValue(isSSRSync);
-  return useSyncExternalStore(emptySubscribe, constFalse, constTrue);
-};
+  useSyncExternalStore(emptySubscribe, lazyFalse, lazyTrue);