build: opt-in pnpm global store makes dev worktrees install in ~1s and delete instantly

.pnpmfile.cjs

@@ -1,21 +1,65 @@
-// Windows WSL dev mode runs the server under Linux from the same node_modules
-// as the Windows client, so Windows installs also need Linux x64 glibc native
-// modules. Other platforms install only their own binaries; setting this
-// everywhere added ~2.2 GB of foreign binaries to every macOS install.
-// Release scripts stage their own installs with explicit architectures.
+// oxlint-disable t3code/no-global-process-runtime -- pnpm loads this file before any Effect runtime exists.
 module.exports = {
   hooks: {
-    updateConfig(config) {
-      // oxlint-disable-next-line t3code/no-global-process-runtime -- pnpm loads this file before any Effect runtime exists.
-      if (process.platform !== "win32") return config;
+    // Many React libraries ship types that import "react" without declaring
+    // @types/react. TypeScript then finds @types/react only by walking up
+    // node_modules from the library's real path. The global virtual store
+    // has no hoisted copy on that path, so the types become `any`. An
+    // optional peer links the consumer's @types/react next to the library.
+    // Our own packages are private (npm never publishes those) and are left
+    // alone: pnpm checks local `file:` packages against the lockfile without
+    // this hook.
+    readPackage(manifest) {
+      if (manifest.private) return manifest;
+      const declaresReact =
+        manifest.peerDependencies?.react !== undefined ||
+        manifest.dependencies?.react !== undefined;
+      if (!declaresReact || manifest.name === "@types/react") return manifest;
+      if (
+        manifest.dependencies?.["@types/react"] !== undefined ||
+        manifest.peerDependencies?.["@types/react"] !== undefined
+      ) {
+        return manifest;
+      }
       return {
-        ...config,
-        supportedArchitectures: {
+        ...manifest,
+        peerDependencies: { ...manifest.peerDependencies, "@types/react": "*" },
+        peerDependenciesMeta: {
+          ...manifest.peerDependenciesMeta,
+          "@types/react": { optional: true },
+        },
+      };
+    },
+    updateConfig(config) {
+      const next = { ...config };
+      // Dev machines link packages from one shared copy in <storeDir>/links,
+      // so a worktree install takes seconds and a worktree delete is instant.
+      // CI keeps per-project stores: pnpm 12 honors an explicit setting there
+      // too, and a fresh runner has nothing to share. Windows is left out:
+      // WSL dev runs the server from the same node_modules, and store links
+      // across that boundary are untested.
+      // T3CODE_PNPM_GLOBAL_VIRTUAL_STORE=0 opts a dev machine out.
+      if (
+        !process.env.CI &&
+        process.platform !== "win32" &&
+        process.env.T3CODE_PNPM_GLOBAL_VIRTUAL_STORE !== "0"
+      ) {
+        next.virtualStoreType = "global";
+      }
+      // Windows WSL dev mode runs the server under Linux from the same
+      // node_modules as the Windows client, so Windows installs also need
+      // Linux x64 glibc native modules. Other platforms install only their own
+      // binaries; setting this everywhere added ~2.2 GB of foreign binaries to
+      // every macOS install. Release scripts stage their own installs with
+      // explicit architectures.
+      if (process.platform === "win32") {
+        next.supportedArchitectures = {
           os: ["current", "linux"],
           cpu: ["current", "x64"],
           libc: ["current", "glibc"],
-        },
-      };
+        };
+      }
+      return next;
     },
   },
 };

apps/desktop/scripts/ensure-electron-runtime.mjs

@@ -32,14 +32,17 @@ function ensureExecutable(filePath) {
   }
 }
 
+// Written through a rename so a concurrent reader never sees a partial file.
 function repairPathFile(electronDir, platformPath) {
   const pathFile = NodePath.join(electronDir, "path.txt");
   const currentPath = NodeFS.existsSync(pathFile)
     ? NodeFS.readFileSync(pathFile, "utf8")
     : undefined;
 
   if (currentPath !== platformPath) {
-    NodeFS.writeFileSync(pathFile, platformPath);
+    const tempPath = `${pathFile}.${process.pid}`;
+    NodeFS.writeFileSync(tempPath, platformPath);
+    NodeFS.renameSync(tempPath, pathFile);
   }
 }
 
@@ -118,12 +121,17 @@ function runChecked(command, args) {
 
 // electron's own installer goes through @electron/get, which reuses its
 // download cache (~/.cache/electron, ~/Library/Caches/electron) and verifies
-// the bundled checksums. pnpm 11 never runs it because electron has no
-// install script, so a new worktree would otherwise download 130 MB again.
-function installFromElectronCache(electronDir) {
+// the bundled checksums. pnpm never runs it because electron has no install
+// script, so a new worktree would otherwise download 130 MB again.
+// install.js extracts next to itself, so it runs from a copy in the stage
+// directory. It still resolves @electron/get from the real package's parents.
+function installFromElectronCache(electronDir, stageDir) {
+  for (const file of ["install.js", "package.json", "checksums.json"]) {
+    NodeFS.copyFileSync(NodePath.join(electronDir, file), NodePath.join(stageDir, file));
+  }
   const result = NodeChildProcess.spawnSync(
     process.execPath,
-    [NodePath.join(electronDir, "install.js")],
+    [NodePath.join(stageDir, "install.js")],
     { stdio: ["ignore", "inherit", "inherit"] },
   );
   if (result.status === 0) {
@@ -135,7 +143,7 @@ function installFromElectronCache(electronDir) {
   return false;
 }
 
-function downloadElectronRuntime(electronDir, version) {
+function downloadElectronRuntime(stageDir, version) {
   const tempDir = NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-electron-"));
   const zipPath = NodePath.join(tempDir, `electron-v${version}-${hostPlatform}-${hostArch}.zip`);
 
@@ -154,23 +162,40 @@ function downloadElectronRuntime(electronDir, version) {
       zipPath,
     ]);
     if (hostPlatform === "darwin") {
-      runChecked("ditto", ["-x", "-k", zipPath, NodePath.join(electronDir, "dist")]);
+      runChecked("ditto", ["-x", "-k", zipPath, NodePath.join(stageDir, "dist")]);
     } else {
       runChecked("python3", [
         "-c",
         "import os, sys, zipfile; os.makedirs(sys.argv[2], exist_ok=True); zipfile.ZipFile(sys.argv[1]).extractall(sys.argv[2])",
         zipPath,
-        NodePath.join(electronDir, "dist"),
+        NodePath.join(stageDir, "dist"),
       ]);
     }
   } finally {
     NodeFS.rmSync(tempDir, { recursive: true, force: true });
   }
 }
 
-function resetRuntime(electronDir) {
-  NodeFS.rmSync(NodePath.join(electronDir, "dist"), { recursive: true, force: true });
-  NodeFS.rmSync(NodePath.join(electronDir, "path.txt"), { force: true });
+// With pnpm's global virtual store, every worktree on this Electron version
+// shares electronDir, and another worktree may run Electron from it. So the
+// runtime is built in a private stage directory and published with one
+// rename. A broken dist is renamed away before it is deleted. If another
+// process publishes first, our rename fails and we keep theirs.
+function publishRuntime(electronDir, stageDir, isValid) {
+  const distPath = NodePath.join(electronDir, "dist");
+  if (isValid()) {
+    return;
+  }
+  try {
+    NodeFS.renameSync(distPath, NodePath.join(stageDir, "broken-dist"));
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  try {
+    NodeFS.renameSync(NodePath.join(stageDir, "dist"), distPath);
+  } catch (error) {
+    if (!["EEXIST", "ENOTEMPTY", "EPERM"].includes(error.code)) throw error;
+  }
 }
 
 export function ensureElectronRuntime() {
@@ -179,15 +204,20 @@ export function ensureElectronRuntime() {
   const electronDir = NodePath.dirname(electronPackageJsonPath);
   const platformPath = getPlatformPath();
   const electronPath = NodePath.join(electronDir, "dist", platformPath);
-  const needsInstall = () =>
-    missingRuntimePaths(electronDir, platformPath).length > 0 ||
-    invalidRuntimePaths(electronDir, platformPath).length > 0;
-
-  if (needsInstall()) {
-    resetRuntime(electronDir);
-    if (!installFromElectronCache(electronDir) || needsInstall()) {
-      resetRuntime(electronDir);
-      downloadElectronRuntime(electronDir, electronPackageJson.version);
+  const runtimeIsValid = (dir) =>
+    missingRuntimePaths(dir, platformPath).length === 0 &&
+    invalidRuntimePaths(dir, platformPath).length === 0;
+
+  if (!runtimeIsValid(electronDir)) {
+    const stageDir = NodeFS.mkdtempSync(NodePath.join(electronDir, ".t3-install-"));
+    try {
+      if (!installFromElectronCache(electronDir, stageDir) || !runtimeIsValid(stageDir)) {
+        NodeFS.rmSync(NodePath.join(stageDir, "dist"), { recursive: true, force: true });
+        downloadElectronRuntime(stageDir, electronPackageJson.version);
+      }
+      publishRuntime(electronDir, stageDir, () => runtimeIsValid(electronDir));
+    } finally {
+      NodeFS.rmSync(stageDir, { recursive: true, force: true });
     }
   }
 

apps/mobile/metro.config.js

@@ -34,7 +34,77 @@ const resolveShikiDependencyRoot = (packageName) => {
   return currentDir;
 };
 
-config.watchFolders = [...new Set([...(config.watchFolders ?? []), workspaceRoot])];
+// With pnpm's global virtual store (see .pnpmfile.cjs), package files live in
+// the shared store, outside the workspace, and Metro only reads files inside
+// watchFolders. Watch the store slot of each package reachable from this app,
+// not the whole store: it holds every project's packages. A slot's
+// node_modules holds the package and links to its dependencies.
+const modulesState = JSON.parse(
+  fs.readFileSync(path.join(workspaceRoot, "node_modules", ".modules.yaml"), "utf8"),
+);
+const isInWorkspace = (dir) => !path.relative(workspaceRoot, dir).startsWith("..");
+const usesGlobalStore = !isInWorkspace(
+  path.resolve(workspaceRoot, "node_modules", modulesState.virtualStoreDir),
+);
+// pnpm still hoists every package here. Store packages are not below it, so
+// Node reaches it through NODE_PATH, and Metro through nodeModulesPaths. Some
+// packages import dependencies they never declare.
+const hoistedModulesDir = path.join(workspaceRoot, "node_modules", ".pnpm", "node_modules");
+
+function globalStoreSlotDirs() {
+  const slotDirs = new Set();
+  const visited = new Set();
+  const pending = [
+    path.join(__dirname, "node_modules"),
+    path.join(workspaceRoot, "node_modules"),
+    hoistedModulesDir,
+  ];
+  while (pending.length > 0) {
+    const modulesDir = pending.pop();
+    if (visited.has(modulesDir)) continue;
+    visited.add(modulesDir);
+    let entries;
+    try {
+      entries = fs.readdirSync(modulesDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    const scoped = path.basename(modulesDir).startsWith("@");
+    for (const entry of entries) {
+      if (entry.name.startsWith(".")) continue;
+      const entryPath = path.join(modulesDir, entry.name);
+      if (!scoped && entry.name.startsWith("@")) {
+        pending.push(entryPath);
+        continue;
+      }
+      let realDir;
+      try {
+        realDir = fs.realpathSync(entryPath);
+      } catch {
+        continue;
+      }
+      if (isInWorkspace(realDir)) {
+        // A workspace package: its own node_modules links into the store.
+        pending.push(path.join(realDir, "node_modules"));
+        continue;
+      }
+      const slotDir = scoped ? path.dirname(path.dirname(realDir)) : path.dirname(realDir);
+      if (!slotDirs.has(slotDir)) {
+        slotDirs.add(slotDir);
+        pending.push(slotDir);
+      }
+    }
+  }
+  return [...slotDirs];
+}
+
+config.watchFolders = [
+  ...new Set([
+    ...(config.watchFolders ?? []),
+    workspaceRoot,
+    ...(usesGlobalStore ? globalStoreSlotDirs() : []),
+  ]),
+];
 config.resolver = {
   ...config.resolver,
   blockList: [
@@ -45,6 +115,9 @@ config.resolver = {
         : []),
     new RegExp(`${escapedWorkspaceRoot}[/\\\\]\\.t3[/\\\\].*`),
   ],
+  ...(usesGlobalStore && {
+    nodeModulesPaths: [...(config.resolver?.nodeModulesPaths ?? []), hoistedModulesDir],
+  }),
   extraNodeModules: {
     ...config.resolver?.extraNodeModules,
     "@t3tools/mobile-third-party-licenses": generatedLicenseModuleRoot,

apps/mobile/modules/t3-source-text/package.json

@@ -15,6 +15,7 @@
   "types": "./index.ts",
   "react-native": "./index.ts",
   "peerDependencies": {
+    "@types/react": "*",
     "react": "*",
     "react-native": "*"
   },

knip.jsonc

@@ -15,6 +15,8 @@
       ],
       "vite": { "entry": [".github/**/*.test.cjs"] },
       "vitest": { "entry": [".github/**/*.test.cjs"] },
+      // `prepare` runs scripts/effect-tsgo-patch.ts, which starts its CLI by path.
+      "ignoreDependencies": ["@effect/tsgo"],
     },
     "scripts": {
       // Knip loads its preprocessor through a CLI option; native verification and

package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "prepare": "effect-tsgo patch && vp config --no-agent",
+    "prepare": "node scripts/effect-tsgo-patch.ts && vp config --no-agent",
     "dev": "node scripts/dev-runner.ts dev",
     "dev:share": "node scripts/dev-runner.ts dev --share",
     "dev:server": "node scripts/dev-runner.ts dev:server",