@backtickjs/react-native-client 0.1.8 → 0.1.10

package/README.md

@@ -12,7 +12,7 @@ npm install @backtickjs/react-native-client
 
 ## Usage
 
-Give `evaluate` the modules a bundle may require, then fetch a screen and draw it. Hold the request, a promise, in state in a component that doesn't suspend, so it outlives the render that waits for it, and draw it with React's `use` under `<Suspense>`:
+Give `evaluate` the module map: the modules a bundle may require, imported as the app starts. Then fetch a screen and draw it. Hold the request, a promise, in state in a component that doesn't suspend, so it outlives the render that waits for it, and draw it with React's `use` under `<Suspense>`:
 
 ```tsx
 import { evaluate } from "@backtickjs/react-native-client";
@@ -20,9 +20,10 @@ import * as React from "react";
 import { Suspense, use, useState } from "react";
 import * as JSXRuntime from "react/jsx-runtime";
 import * as ReactNative from "react-native";
+import { ActivityIndicator } from "react-native";
 
 // What a screen may require: the packages this app was built with.
-const modules = {
+const moduleMap = {
   react: React,
   "react/jsx-runtime": JSXRuntime,
   "react-native": ReactNative,
@@ -33,15 +34,13 @@ async function fetchScreen(url: string) {
   if (!response.ok) {
     throw new Error(`${url} answered ${response.status}.`);
   }
-  return evaluate(await response.text(), modules) as React.ReactNode;
+  return evaluate(await response.text(), moduleMap) as React.ReactNode;
 }
 
 export default function App() {
-  const [screen] = useState(() =>
-    fetchScreen("https://api.example.com/screens/home"),
-  );
+  const [screen] = useState(() => fetchScreen("https://api.example.com/"));
   return (
-    <Suspense fallback={<ReactNative.ActivityIndicator />}>
+    <Suspense fallback={<ActivityIndicator />}>
       <Screen screen={screen} />
     </Suspense>
   );
@@ -54,13 +53,13 @@ function Screen({ screen }: { screen: Promise<React.ReactNode> }) {
 
 Wrap the `<Suspense>` in an error boundary to show a screen that couldn't be fetched or run. To fetch again, set a new promise in state. The React Native template of [create-backtick-app](https://github.com/backtickjs/backtick/tree/main/packages/create-backtick-app) has the full version, with the boundary and a refetch whenever the development server restarts.
 
-The server bundles for the versions the app runs: it passes them to `bundler.build` as `packageVersions`, so they should match the packages you put in `modules`.
+The server bundles for the versions the app runs: it passes them to `bundler.build` as `modules`, so they should match the packages in your module map.
 
 ## API
 
-### `evaluate(code: string, modules: Modules): unknown`
+### `evaluate(code: string, moduleMap: ModuleMap): unknown`
 
-Runs `code` as a CommonJS module, with `require` answered from `modules`, and returns what it exports: for a Backtick screen, the element to draw. A bundle that requires a specifier missing from `modules` throws:
+Runs `code` as a CommonJS module, with `require` answered from `moduleMap`, and returns what it exports: for a Backtick screen, the element to draw. A bundle that requires a specifier missing from `moduleMap` throws:
 
 ```
 The bundle requires "expo-haptics", which this app doesn't provide.
@@ -68,13 +67,27 @@ The bundle requires "expo-haptics", which this app doesn't provide.
 
 Errors thrown while the bundle runs propagate to the caller.
 
-### `Modules`
+### `ModuleMap`
+
+```ts
+type ModuleMap = Readonly<Record<string, unknown>>;
+```
+
+What a bundle may require, by specifier, each as the module the app imported for it. It does for an app what a web page's import map does, with modules for values instead of URLs. At least `react`, `react/jsx-runtime` and `react-native`; add any other package the app chooses to offer its screens. Imported at the top of a file, the modules load as the app starts, so one that fails to load fails then, rather than on the first screen that needs it.
+
+### `buildIdFrom(extra: unknown, platform: string): string`
+
+This build's id on `platform`, read from the app config's `extra.buildIds`, which an `app.config.ts` fills with [`@backtickjs/builds`](https://github.com/backtickjs/backtick/tree/main/packages/builds). The id names the modules the build carries, so the server bundles only screens it can run. Send it to the server however the app reaches it, as a header or a GraphQL variable:
 
 ```ts
-type Modules = Readonly<Record<string, unknown>>;
+import { buildIdFrom } from "@backtickjs/react-native-client";
+import Constants from "expo-constants";
+import { Platform } from "react-native";
+
+const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
 ```
 
-What a bundle may require, by specifier, each as its module namespace. At least `react`, `react/jsx-runtime` and `react-native`; add any other package the app chooses to offer its screens.
+It throws when the config has no build id for the platform, as the app starts: no screen could be drawn for a build without one.
 
 ## Security
 
@@ -84,7 +97,7 @@ What a bundle may require, by specifier, each as its module namespace. At least
 
 - [`@backtickjs/core`](https://github.com/backtickjs/backtick/tree/main/packages/core): `cs` and the types for writing screens
 - [`@backtickjs/bundler`](https://github.com/backtickjs/backtick/tree/main/packages/bundler): builds the bundles this runs
-- [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/packages/react-native): React Native's components and APIs, to splice into scripts
+- [`@backtickjs/react-native`](https://github.com/backtickjs/backtick/tree/main/adapters/react-native): React Native's components and APIs, to splice into scripts
 - [`create-backtick-app`](https://github.com/backtickjs/backtick/tree/main/packages/create-backtick-app): an Expo app with a Backtick server beside it
 - [How it works](https://backtickjs.com/docs/how-it-works)
 - [Errors](https://backtickjs.com/docs/errors)

package/dist/index.d.ts

@@ -1,24 +1,39 @@
 /**
- * What a bundle may require, by specifier: the packages the app was built
- * with, each as its module. At least React, React Native and React's JSX
+ * What a bundle may import, by specifier: each the module the app imported
+ * for it. What a web page's import map does, for an app, with modules for
+ * values instead of URLs. At least React, React Native and React's JSX
  * runtime:
  *
  *     import * as React from "react";
  *     import * as JSXRuntime from "react/jsx-runtime";
  *     import * as ReactNative from "react-native";
  *
- *     const modules = {
- *       "react": React,
+ *     export const moduleMap = {
+ *       react: React,
  *       "react/jsx-runtime": JSXRuntime,
  *       "react-native": ReactNative,
- *     };
+ *     } satisfies ModuleMap;
+ *
+ * Imported as the app starts, so a module that fails to load fails then, not
+ * on the first screen that needs it.
  */
-export type Modules = Readonly<Record<string, unknown>>;
+export type ModuleMap = Readonly<Record<string, unknown>>;
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export declare function evaluate(code: string, modules: Modules): unknown;
+export declare function evaluate(code: string, moduleMap: ModuleMap): unknown;
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export declare function buildIdFrom(extra: unknown, platform: string): string;

package/dist/index.js

@@ -1,19 +1,38 @@
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export function evaluate(code, modules) {
-    const module = { exports: {} };
+export function evaluate(code, moduleMap) {
     const require = (specifier) => {
-        if (!Object.hasOwn(modules, specifier)) {
+        if (!Object.hasOwn(moduleMap, specifier)) {
             throw new Error(`The bundle requires "${specifier}", which this app doesn't provide.`);
         }
-        return modules[specifier];
+        return moduleMap[specifier];
     };
+    const module = { exports: {} };
     new Function("module", "exports", "require", code)(module, module.exports, require);
     return module.exports;
 }
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export function buildIdFrom(extra, platform) {
+    const ids = extra
+        ?.buildIds;
+    const id = ids?.[platform];
+    if (typeof id !== "string") {
+        throw new Error(`No build id for ${platform} in the app config: is app.config.ts adding buildIds from @backtickjs/builds?`);
+    }
+    return id;
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,OAAgB;IACrD,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,OAAO,OAAO,CAAC,SAAS,CAAC,CAAC;IAC5B,CAAC,CAAC;IACF,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAChD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,SAAoB;IACzD,MAAM,OAAO,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC7C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,wBAAwB,SAAS,oCAAoC,CACtE,CAAC;QACJ,CAAC;QACD,OAAO,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,OAAO,EAAE,EAAa,EAAE,CAAC;IAC1C,IAAI,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,CAChD,MAAM,EACN,MAAM,CAAC,OAAO,EACd,OAAO,CACR,CAAC;IACF,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,QAAgB;IAC1D,MAAM,GAAG,GAAI,KAA4D;QACvE,EAAE,QAAQ,CAAC;IACb,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,mBAAmB,QAAQ,+EAA+E,CAC3G,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtickjs/react-native-client",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Runs a Backtick server's screens in a React Native app, with the app's own packages",
   "keywords": [
     "backtick",

package/src/index.ts

@@ -1,37 +1,41 @@
 /**
- * What a bundle may require, by specifier: the packages the app was built
- * with, each as its module. At least React, React Native and React's JSX
+ * What a bundle may import, by specifier: each the module the app imported
+ * for it. What a web page's import map does, for an app, with modules for
+ * values instead of URLs. At least React, React Native and React's JSX
  * runtime:
  *
  *     import * as React from "react";
  *     import * as JSXRuntime from "react/jsx-runtime";
  *     import * as ReactNative from "react-native";
  *
- *     const modules = {
- *       "react": React,
+ *     export const moduleMap = {
+ *       react: React,
  *       "react/jsx-runtime": JSXRuntime,
  *       "react-native": ReactNative,
- *     };
+ *     } satisfies ModuleMap;
+ *
+ * Imported as the app starts, so a module that fails to load fails then, not
+ * on the first screen that needs it.
  */
-export type Modules = Readonly<Record<string, unknown>>;
+export type ModuleMap = Readonly<Record<string, unknown>>;
 
 /**
- * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * A bundle's code, run as CommonJS with `require` answered from `moduleMap`:
  * what it exports, the screen to draw. What a web page's import map and
  * script tag do for a browser, this does for an app; fetching the bundle, and
  * when, is the app's. A bundle requiring a module the app doesn't provide
  * throws.
  */
-export function evaluate(code: string, modules: Modules): unknown {
-  const module = { exports: {} as unknown };
+export function evaluate(code: string, moduleMap: ModuleMap): unknown {
   const require = (specifier: string): unknown => {
-    if (!Object.hasOwn(modules, specifier)) {
+    if (!Object.hasOwn(moduleMap, specifier)) {
       throw new Error(
         `The bundle requires "${specifier}", which this app doesn't provide.`,
       );
     }
-    return modules[specifier];
+    return moduleMap[specifier];
   };
+  const module = { exports: {} as unknown };
   new Function("module", "exports", "require", code)(
     module,
     module.exports,
@@ -39,3 +43,25 @@ export function evaluate(code: string, modules: Modules): unknown {
   );
   return module.exports;
 }
+
+/**
+ * This build's id on `platform`, from the app config's `extra`, where an
+ * `app.config.ts` puts `buildIds` from `@backtickjs/builds`: it names the
+ * modules the build carries, for the server to bundle screens it can run.
+ * Send it however the app reaches its server: a header, a GraphQL variable.
+ * Throws for an app config without it, as the app starts: no screen could be
+ * drawn for a build without an id.
+ *
+ *     const buildId = buildIdFrom(Constants.expoConfig?.extra, Platform.OS);
+ */
+export function buildIdFrom(extra: unknown, platform: string): string {
+  const ids = (extra as { buildIds?: Record<string, unknown> } | undefined)
+    ?.buildIds;
+  const id = ids?.[platform];
+  if (typeof id !== "string") {
+    throw new Error(
+      `No build id for ${platform} in the app config: is app.config.ts adding buildIds from @backtickjs/builds?`,
+    );
+  }
+  return id;
+}