@rn-iso/expo-build-cache 0.14.0

package/README.md

@@ -0,0 +1,47 @@
+# @rn-iso/expo-build-cache
+
+A local Expo build cache provider. When no native input has changed, the CLI
+installs a cached `.app` / `.apk` instead of compiling — which is the difference
+between a JS-only change costing a simulator boot and costing a full native
+build.
+
+Local on purpose: a directory under `$HOME` shared by every worktree on the
+machine. No account, no network, and a second worktree building the same commit
+is a hit rather than a second five-minute build.
+
+```bash
+npm i -D @rn-iso/expo-build-cache
+```
+
+Point your Expo config at it. **Which key depends on the SDK, and the wrong one
+is a silent no-op rather than an error:**
+
+```jsonc
+// SDK 54+
+{ "expo": { "buildCacheProvider": { "plugin": "@rn-iso/expo-build-cache" } } }
+
+// SDK 53 — reads only the experiments key and ignores the top-level one
+{ "expo": { "experiments": { "buildCacheProvider": { "plugin": "@rn-iso/expo-build-cache" } } } }
+```
+
+Add a `.fingerprintignore` for anything that changes without changing the build.
+`ios/Podfile.lock` is the usual culprit: pod checksums can embed absolute paths,
+which makes the fingerprint differ per machine and the cache never hit.
+
+Watch for `[build-cache] hit` or `miss` in the output. A miss means you changed
+something native — or that you are the first workspace on this commit.
+
+### Housekeeping
+
+The cache registers itself with [`rn-iso`](https://www.npmjs.com/package/rn-iso)
+if it is installed, so it can be reported and trimmed:
+
+```bash
+npx rn-iso gc --caches                            # what it has grown to
+npx rn-iso gc --caches --delete --older-than 30   # drop entries unused for 30 days
+```
+
+rn-iso is an optional peer. Without it the cache works exactly the same; it is
+just invisible to housekeeping.
+
+`RN_ISO_BUILD_CACHE` overrides the location.

package/index.js

@@ -0,0 +1,111 @@
+// A local Expo build cache provider.
+//
+// Expo fingerprints the project's native inputs and hands the hash to a
+// provider. If a build already exists for that hash, the provider returns it and
+// the CLI installs it instead of compiling. That is the difference between a
+// JS-only change costing a simulator boot and costing a full native build, and
+// most changes are JS-only.
+//
+// Local on purpose: a directory under $HOME shared by every worktree on the
+// machine. No account, no network, and a second worktree building the same
+// commit is a hit rather than a second five-minute build.
+//
+// Wire it up in app.json. Which key depends on the SDK, and the wrong one is a
+// silent no-op rather than an error:
+//
+//   SDK 54+  { "expo": { "buildCacheProvider": { "plugin": "@rn-iso/expo-build-cache" } } }
+//   SDK 53   { "expo": { "experiments": { "buildCacheProvider": { ... } } } }
+//
+// SDK 53's CLI reads only the experiments key and ignores the top-level one
+// without saying so; SDK 54+ reads the top-level key and falls back to
+// experiments.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const CACHE_ROOT =
+  process.env.RN_ISO_BUILD_CACHE || path.join(os.homedir(), '.rn-iso-build-cache');
+
+function entryDir(platform, fingerprintHash) {
+  return path.join(CACHE_ROOT, platform, fingerprintHash);
+}
+
+// The cached artifact is the single .app / .apk inside the entry directory.
+function artifactIn(dir) {
+  if (!fs.existsSync(dir)) return null;
+  const found = fs.readdirSync(dir).find(f => f.endsWith('.app') || f.endsWith('.apk'));
+  return found ? path.join(dir, found) : null;
+}
+
+// Tell rn-iso this cache exists, so `gc --caches` can report and trim it. Every
+// entry is an independent directory keyed by fingerprint, hence prune: entries.
+//
+// Best effort by design: this package is useful without rn-iso installed, and a
+// missing peer must never break a build. Registration is idempotent, so calling
+// it on every resolve is fine.
+let registered = false;
+function registerOnce() {
+  if (registered) return;
+  registered = true;
+  try {
+    // eslint-disable-next-line global-require
+    const { register } = require('rn-iso/cache-manifest');
+    register({
+      dir: CACHE_ROOT,
+      name: 'Expo build cache',
+      prune: 'entries',
+      note: 'built .app/.apk keyed on the native fingerprint',
+    });
+  } catch {
+    // rn-iso not installed, or too old to export the manifest. Nothing to do.
+  }
+}
+
+// The hash the CLI passes is stable once .fingerprintignore excludes generated
+// files that embed absolute paths -- ios/Podfile.lock is the usual culprit, as
+// pod checksums can carry machine-specific paths. Use it directly rather than
+// recomputing: fingerprinting walks node_modules and is otherwise the single
+// largest cost of a cache hit.
+async function resolveBuildCache({ platform, fingerprintHash }) {
+  registerOnce();
+  const key = fingerprintHash;
+  const hit = artifactIn(entryDir(platform, key));
+  if (hit) {
+    console.log(`[build-cache] hit ${platform} ${key.slice(0, 12)}`);
+    // Touch on hit so age-based trimming can tell a working entry from a dead
+    // one. Without this, the entries earning their keep look identical to the
+    // ones nothing has used in months.
+    fs.utimesSync(path.dirname(hit), new Date(), new Date());
+    return hit;
+  }
+  console.log(`[build-cache] miss ${platform} ${key.slice(0, 12)}`);
+  return null;
+}
+
+async function uploadBuildCache({ platform, fingerprintHash, buildPath }) {
+  registerOnce();
+  if (!buildPath || !fs.existsSync(buildPath)) return null;
+
+  const key = fingerprintHash;
+  const dest = entryDir(platform, key);
+  if (artifactIn(dest)) return artifactIn(dest);
+
+  // Stage in a sibling and rename into place. A copy interrupted halfway must
+  // never be readable as a complete entry by a worktree building in parallel,
+  // and rename is the only step that is atomic.
+  const staging = `${dest}.staging-${process.pid}`;
+  fs.rmSync(staging, { recursive: true, force: true });
+  fs.mkdirSync(staging, { recursive: true });
+  execFileSync('cp', ['-R', buildPath, path.join(staging, path.basename(buildPath))]);
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.rmSync(dest, { recursive: true, force: true });
+  fs.renameSync(staging, dest);
+
+  console.log(`[build-cache] stored ${platform} ${key.slice(0, 12)}`);
+  return artifactIn(dest);
+}
+
+module.exports = { resolveBuildCache, uploadBuildCache, CACHE_ROOT };

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@rn-iso/expo-build-cache",
+  "version": "0.14.0",
+  "description": "Local Expo build cache provider: installs a cached .app/.apk instead of compiling when no native input changed.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "rn-iso": ">=0.14.0"
+  },
+  "peerDependenciesMeta": {
+    "rn-iso": {
+      "optional": true
+    }
+  }
+}