create-apollo-suite-monorepo 1.0.1469 → 1.0.1470

package/README.md

@@ -238,12 +238,23 @@ them, after `pnpm backend:update` has brought in a backend with
 
 ## Deploying to production
 
-The scaffold pins `packageManager: "pnpm@11.0.0"` so Corepack picks the right
-pnpm. If your CI / deploy host installs pnpm separately, **make sure it's
-pnpm 11+** — pnpm 11 sets `strictDepBuilds: true` by default and reads the
-allow-list from `allowBuilds` in `pnpm-workspace.yaml`. pnpm 10 silently
-ignores `allowBuilds`; pnpm 11 silently ignores the deprecated
-`onlyBuiltDependencies`. Mixing the two leads to `sharp` (and `esbuild`,
+The scaffold pins `packageManager: "pnpm@12.15.0"` (the version lives in
+`pnpm-policy.mjs`), so Corepack or pnpm itself switches to it. If your CI /
+deploy host installs pnpm separately, **make sure it's pnpm 12+** — pnpm sets
+`strictDepBuilds: true` by default and reads the allow-list from `allowBuilds`
+in `pnpm-workspace.yaml`; pnpm 10 silently ignores `allowBuilds`, and pnpm 11+
+silently ignores the deprecated `onlyBuiltDependencies`. Once the version is
+pinned, pnpm 12 fails (`ERR_PNPM_UNRECOGNIZED_WORKSPACE_SETTINGS`) on any key
+in `pnpm-workspace.yaml` it does not know. No `.npmrc` is generated: pnpm 11+
+reads it only for auth and registry, so the install settings it used to carry
+(`engineStrict`, `autoInstallPeers`, `strictPeerDependencies`,
+`publicHoistPattern`, `shellEmulator`) live in `pnpm-workspace.yaml`.
+⚠️ pnpm 12 also ignores a registry token written as an environment variable
+in a **project** `.npmrc`. It warns `environment variables are not expanded in
+repository-controlled registry credentials` and installs without the token.
+On a CI or deploy host that installs from a private registry, put the token in
+the user-level `~/.npmrc` or pnpm's global config instead.
+Mixing up the build allow-list leads to `sharp` (and `esbuild`,
 `@swc/core`, …) skipping their postinstalls, which surfaces at runtime as:
 
 ```

package/index.mjs

@@ -20,6 +20,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync, symli
 import { resolve, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { NODE_VERSION, NODE_RANGE, assertSupportedNode } from "./node-policy.mjs";
+import { PNPM_VERSION, PNPM_RANGE } from "./pnpm-policy.mjs";
 import { createInterface } from "node:readline";
 import {
   APPS_FILE_ENV_VALUE,
@@ -244,7 +245,7 @@ function preflight(flags) {
   // `pnpm backend:setup`, and `pnpm backend:upgrade` will fail without it.
   const TOOLS = [
     { cmd: "git",  required: true,  missing: "git is required but not found.\n  Install: https://git-scm.com/" },
-    { cmd: "pnpm", required: false, missing: "pnpm not found — install with: npm i -g pnpm  (required for workspaces)" },
+    { cmd: "pnpm", required: false, missing: `pnpm not found — install with: npm i -g pnpm@${PNPM_VERSION}  (required for workspaces)` },
     { cmd: "bun",  required: false, missing:
         "bun not found — required by apps/backend for db:push, db:seed,\n" +
         "       plugins:build, and the upgrade pipeline.\n" +
@@ -416,13 +417,14 @@ export function writeRootPackageJson(targetDir, dirName) {
       // never hits this; pnpm skips them, so the monorepo must ask for it.
       "@opentelemetry/api": "^1.9.0",
     },
-    // Pin to pnpm 11 because `pnpm-workspace.yaml` uses the `allowBuilds`
-    // map format introduced in v11 (deprecated `onlyBuiltDependencies` is
-    // silently ignored on v11 — sharp/esbuild postinstalls then no-op and
-    // /admin/media crashes at runtime with "Cannot find module sharp-…").
-    // Corepack uses this field to auto-fetch the right pnpm.
-    packageManager: "pnpm@11.0.0",
-    engines: { node: NODE_RANGE, pnpm: ">=11" },
+    // Pinned exactly so Corepack / pnpm's own version switching fetch it;
+    // the version lives in pnpm-policy.mjs. `pnpm-workspace.yaml` uses the
+    // `allowBuilds` map, which needs pnpm >= 11 (older pnpm ignores it —
+    // sharp/esbuild postinstalls then no-op and /admin/media crashes at
+    // runtime with "Cannot find module sharp-…"). pnpm 12 also rejects any
+    // unknown pnpm-workspace.yaml key once the project pins it.
+    packageManager: `pnpm@${PNPM_VERSION}`,
+    engines: { node: NODE_RANGE, pnpm: PNPM_RANGE },
   };
   // Copy the policy into the new project: it must work before the backend exists.
   const scriptsDir = resolve(targetDir, "scripts");
@@ -437,21 +439,8 @@ export function writeRootPackageJson(targetDir, dirName) {
   pkg.scripts.preinstall = "node scripts/require-supported-node.mjs";
   writeFileSync(resolve(targetDir, "package.json"), JSON.stringify(pkg, null, 2) + "\n");
 
-  // .npmrc — keep peer-deps lenient and hoist esbuild's platform binaries so
-  // its postinstall version check resolves the correct one across nested
-  // dependency trees.
-  writeFileSync(
-    resolve(targetDir, ".npmrc"),
-    [
-      "engine-strict=true",
-      "auto-install-peers=true",
-      "strict-peer-dependencies=false",
-      "public-hoist-pattern[]=*esbuild*",
-      "public-hoist-pattern[]=*types*",
-      "shell-emulator=true",
-      "",
-    ].join("\n"),
-  );
+  // No .npmrc: pnpm >= 11 reads it only for auth and registry, so the install
+  // settings it used to carry live in pnpm-workspace.yaml (writePnpmWorkspace).
 }
 
 // Link an app's .env.local to the monorepo root .env.local so the root file
@@ -476,14 +465,15 @@ function linkRootEnvLocal(targetDir, appRelPath, fallbackLines) {
   }
 }
 
-function writePnpmWorkspace(targetDir) {
+export function writePnpmWorkspace(targetDir) {
   // pnpm 11 replaced `onlyBuiltDependencies` (list) with `allowBuilds`
-  // (map of package -> bool). apollo-cms transitively pulls multiple
-  // esbuild versions (0.18, 0.25, 0.27); pnpm's binary symlink can pick
-  // the wrong platform binary for esbuild's postinstall version check,
-  // failing with "Expected X.Y.Z but got A.B.C". Allow listed packages
+  // (map of package -> bool); pnpm 12 still ignores the old key silently.
+  // apollo-cms transitively pulls multiple esbuild versions (0.18, 0.25,
+  // 0.27); pnpm's binary symlink can pick the wrong platform binary for
+  // esbuild's postinstall version check, failing with
+  // "Expected X.Y.Z but got A.B.C". Allow listed packages
   // to run their build/postinstall scripts; the rest are skipped
-  // (pnpm 11 default is `strictDepBuilds: true`, empty allow-map).
+  // (default is `strictDepBuilds: true`, empty allow-map).
   // See https://pnpm.io/blog/releases/11.0.
   const yaml = [
     "packages:",
@@ -515,6 +505,18 @@ function writePnpmWorkspace(targetDir) {
     "  'sharp': true",
     "  'unrs-resolver': true",
     "",
+    "# Moved from .npmrc, which pnpm >= 11 reads only for auth/registry.",
+    "# Peers stay lenient; esbuild's platform binaries are hoisted so its",
+    "# postinstall version check resolves the right one; *types* hoisted;",
+    "# the engines check is enforced; scripts run in a cross-platform shell.",
+    "engineStrict: true",
+    "autoInstallPeers: true",
+    "strictPeerDependencies: false",
+    "publicHoistPattern:",
+    "  - '*esbuild*'",
+    "  - '*types*'",
+    "shellEmulator: true",
+    "",
   ].join("\n");
   writeFileSync(resolve(targetDir, "pnpm-workspace.yaml"), yaml);
 }
@@ -2179,7 +2181,7 @@ async function main() {
     warn(`Run later:\n      cd ${dirName} && pnpm install`);
   } else if (!commandExists("pnpm")) {
     step(7, "Skipping dependency installation (pnpm not installed)");
-    warn(`Install pnpm and run:\n      npm i -g pnpm && cd ${dirName} && pnpm install`);
+    warn(`Install pnpm and run:\n      npm i -g pnpm@${PNPM_VERSION} && cd ${dirName} && pnpm install`);
   } else {
     step(7, "Installing dependencies (pnpm)");
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apollo-suite-monorepo",
-  "version": "1.0.1469",
+  "version": "1.0.1470",
   "description": "Scaffold a monorepo with a frontend app and Apollo CMS as a git submodule backend (single-origin via Next.js rewrites + assetPrefix)",
   "bin": {
     "create-apollo-suite-monorepo": "index.mjs"

package/pnpm-policy.mjs

@@ -0,0 +1,11 @@
+/**
+ * pnpm 12 is the package manager a scaffolded monorepo pins. The scaffold
+ * (index.mjs) writes it into a new project's package.json, and the backend's
+ * scripts/sync-root-workspace.mjs moves an existing project up to it on the
+ * next `pnpm backend:update`. Update the version here only.
+ *
+ * Exact, because Corepack and pnpm's own version switching need one.
+ */
+export const PNPM_VERSION = '12.15.0';
+export const PNPM_MAJOR = Number(PNPM_VERSION.split('.')[0]);
+export const PNPM_RANGE = `>=${PNPM_MAJOR}`;