@backtickjs/react-native-client 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

@@ -0,0 +1,93 @@
+# @backtickjs/react-native-client
+
+Runs a [Backtick](https://backtickjs.com) server's screens in a React Native app. Your server runs its server components per request and answers with a bundle: one JavaScript file holding the screen's data and its compiled client scripts. `evaluate` runs that bundle with the app's own React and React Native and returns the screen to draw. It is what a web page's import map and script tag do for a browser, in under 1 KB.
+
+Fetching the bundle stays with the app, on purpose: headers, auth, caching and when to fetch again are yours.
+
+## Install
+
+```sh
+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>`:
+
+```tsx
+import { evaluate } from "@backtickjs/react-native-client";
+import * as React from "react";
+import { Suspense, use, useState } from "react";
+import * as JSXRuntime from "react/jsx-runtime";
+import * as ReactNative from "react-native";
+
+// What a screen may require: the packages this app was built with.
+const modules = {
+  react: React,
+  "react/jsx-runtime": JSXRuntime,
+  "react-native": ReactNative,
+};
+
+async function fetchScreen(url: string) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`${url} answered ${response.status}.`);
+  }
+  return evaluate(await response.text(), modules) as React.ReactNode;
+}
+
+export default function App() {
+  const [screen] = useState(() =>
+    fetchScreen("https://api.example.com/screens/home"),
+  );
+  return (
+    <Suspense fallback={<ReactNative.ActivityIndicator />}>
+      <Screen screen={screen} />
+    </Suspense>
+  );
+}
+
+function Screen({ screen }: { screen: Promise<React.ReactNode> }) {
+  return use(screen);
+}
+```
+
+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`.
+
+## API
+
+### `evaluate(code: string, modules: Modules): 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:
+
+```
+The bundle requires "expo-haptics", which this app doesn't provide.
+```
+
+Errors thrown while the bundle runs propagate to the caller.
+
+### `Modules`
+
+```ts
+type Modules = Readonly<Record<string, unknown>>;
+```
+
+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.
+
+## Security
+
+`evaluate` runs the bundle with `new Function`, which works on Hermes and JavaScriptCore. A bundle is code with the app's full abilities, so the server is trusted: serve screens over HTTPS from an endpoint you control.
+
+## Related
+
+- [`@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
+- [`create-backtick-app`](https://github.com/backtickjs/backtick/tree/main/packages/create-backtick-app): an Expo app with a Backtick server beside it
+- [Documentation](https://backtickjs.com/docs)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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
+ * runtime:
+ *
+ *     import * as React from "react";
+ *     import * as JSXRuntime from "react/jsx-runtime";
+ *     import * as ReactNative from "react-native";
+ *
+ *     const modules = {
+ *       "react": React,
+ *       "react/jsx-runtime": JSXRuntime,
+ *       "react-native": ReactNative,
+ *     };
+ */
+export type Modules = Readonly<Record<string, unknown>>;
+/**
+ * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * 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;

package/dist/index.js

@@ -0,0 +1,19 @@
+/**
+ * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * 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: {} };
+    const require = (specifier) => {
+        if (!Object.hasOwn(modules, specifier)) {
+            throw new Error(`The bundle requires "${specifier}", which this app doesn't provide.`);
+        }
+        return modules[specifier];
+    };
+    new Function("module", "exports", "require", code)(module, module.exports, require);
+    return module.exports;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@backtickjs/react-native-client",
+  "version": "0.1.0",
+  "description": "Runs a Backtick server's screens in a React Native app, with the app's own packages",
+  "keywords": [
+    "backtick",
+    "react-native",
+    "server-driven-ui",
+    "server-components",
+    "client",
+    "evaluate"
+  ],
+  "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/react-native-client"
+  },
+  "license": "MIT",
+  "author": "Jean-François Bisson <jf@backtickjs.com>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/._cache",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "prettier": "^3.6.2",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "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,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
+ * runtime:
+ *
+ *     import * as React from "react";
+ *     import * as JSXRuntime from "react/jsx-runtime";
+ *     import * as ReactNative from "react-native";
+ *
+ *     const modules = {
+ *       "react": React,
+ *       "react/jsx-runtime": JSXRuntime,
+ *       "react-native": ReactNative,
+ *     };
+ */
+export type Modules = Readonly<Record<string, unknown>>;
+
+/**
+ * A bundle's code, run as CommonJS with `require` answered from `modules`:
+ * 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 };
+  const require = (specifier: string): unknown => {
+    if (!Object.hasOwn(modules, specifier)) {
+      throw new Error(
+        `The bundle requires "${specifier}", which this app doesn't provide.`,
+      );
+    }
+    return modules[specifier];
+  };
+  new Function("module", "exports", "require", code)(
+    module,
+    module.exports,
+    require,
+  );
+  return module.exports;
+}