From dc2370288a86c6c016f6bcf53203d5b5a00214c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 16 Oct 2026 09:32:28 +0000 Subject: [PATCH] docs(deployment): name the npm 10 `edgesOut` install failure and its two remedies npm 10 (the npm Node 22 ships) cannot install @objectstack/cli or @objectstack/plugin-auth: better-auth's optional vitest peer resolves to vitest@4.1.12, whose @vitest/browser-webdriverio peer set is incoherent. - self-hosting: the self-built runtime recipe installs under a pinned npm 11 the way docker/Dockerfile does (and with the image's pg/mysql2 drivers, so "equivalent" holds); the host install upgrades npm to 11 first. - troubleshooting: one Installation Issues entry, findable by the error text, with both remedies and when the entry can be removed. - getting-started: a short npm 10 note at both Prerequisites tables. Claude-Session: https://claude.ai/code/session_016PVjjuVPte5XEJvaQx1E4t Co-authored-by: Claude --- content/docs/deployment/self-hosting.mdx | 15 ++++++++++++- content/docs/deployment/troubleshooting.mdx | 21 +++++++++++++++++++ content/docs/getting-started/index.mdx | 9 ++++++++ .../getting-started/your-first-project.mdx | 9 ++++++++ 4 files changed, 53 insertions(+), 1 deletion(-) diff --git a/content/docs/deployment/self-hosting.mdx b/content/docs/deployment/self-hosting.mdx index e4262a0a00c..61f911d836b 100644 --- a/content/docs/deployment/self-hosting.mdx +++ b/content/docs/deployment/self-hosting.mdx @@ -168,7 +168,14 @@ image)? The official image is nothing more than: ```dockerfile title="Dockerfile (self-built runtime, equivalent)" FROM node:22-slim -RUN npm install -g @objectstack/cli@17.7.0 +# node:22-slim ships npm 10, which fails this install with "reading 'edgesOut'" +# (see Troubleshooting). Install under a pinned npm 11, deleted in the same layer. +RUN npm install --prefix /tmp/os-installer-npm --no-save --no-audit --no-fund "npm@11.21.0" \ + && export PATH="/tmp/os-installer-npm/node_modules/.bin:$PATH" \ + && test "$(npm --version)" = "11.21.0" \ + && npm install -g @objectstack/cli@17.7.0 "pg@^8.0.0" "mysql2@^3.0.0" \ + && npm cache clean --force \ + && rm -rf /tmp/os-installer-npm WORKDIR /srv/app RUN chown node:node /srv/app @@ -355,8 +362,14 @@ configuration-management estate already owns process supervision, or when you are debugging directly on the box. It needs Node 22+ and the CLI on a Linux host, and nothing else. +Install the CLI with npm 11. npm 10, the npm that Node 22 ships, fails with +`Cannot read properties of null (reading 'edgesOut')`, and a global install +reads no `overrides`, so upgrading npm is the only fix here +([Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install)). + ```bash # On the host — no repo clone, just the CLI and your artifact +npm install -g npm@11 # npm 11 needs Node 22.9+ npm install -g @objectstack/cli npm install -g pg # Postgres driver is an optional peer of @objectstack/driver-sql — # install it next to the CLI, or the boot fails loudly (use mysql2 for OS_DATABASE_URL=mysql://…) diff --git a/content/docs/deployment/troubleshooting.mdx b/content/docs/deployment/troubleshooting.mdx index 0bfac4957ba..8777b802677 100644 --- a/content/docs/deployment/troubleshooting.mdx +++ b/content/docs/deployment/troubleshooting.mdx @@ -8,6 +8,27 @@ Solutions to the most common issues encountered when working with ObjectStack. --- +## Installation Issues + +### "Cannot read properties of null (reading 'edgesOut')" from npm install + +**Symptom:** npm exits 1 with `npm error Cannot read properties of null (reading 'edgesOut')` while installing `@objectstack/cli` or `@objectstack/plugin-auth`. This includes the install step of `npm create objectstack` and `npm install -g @objectstack/cli`. + +**Cause:** npm 10, the npm that Node 22 ships, crashes on an optional `vitest` peer in the auth library's dependency tree: the newest vitest 4 has no matching `@vitest/browser-webdriverio` release. npm 11 and pnpm install the same packages, and `npm ci` from a committed lockfile is not affected. + +**Fix** (either one): + +1. **Use npm 11** (it needs Node 22.9+): run `npm install -g npm@11`, then repeat the install. This is the only fix for `npm install -g`, because a global install reads no `overrides`. In a Dockerfile, install under a pinned npm 11, as the [self-built runtime recipe](/docs/deployment/self-hosting#docker-official-image--the-standard-path) does. +2. **Stay on npm 10 and pin vitest** in your project's root `package.json`. Then run `npm install` again and commit the lockfile: + + ```json title="package.json" + "overrides": { "vitest": "~4.0.0" } + ``` + +This entry, the npm 11 steps in [Self-hosting](/docs/deployment/self-hosting), and the npm 10 notes in [Getting Started](/docs/getting-started#prerequisites) and [Your First Project](/docs/getting-started/your-first-project#prerequisites) can be removed once `@vitest/browser-webdriverio` publishes the version that `npm view vitest dist-tags` lists as `V4`, and a plain npm 10 install of `@objectstack/plugin-auth` passes. + +--- + ## Validation Errors ### "Invalid enum value" for field type diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx index a48e7949cf3..dfbe403d3e5 100644 --- a/content/docs/getting-started/index.mdx +++ b/content/docs/getting-started/index.mdx @@ -169,6 +169,15 @@ Before you start, make sure you have the following installed: That's everything the standard path needs — `npx create-objectstack my-app` scaffolds a project with its own TypeScript toolchain and npm scripts. + +**npm 10 cannot install the CLI right now.** npm 10, the npm that Node 22 ships, +fails with `Cannot read properties of null (reading 'edgesOut')`. Upgrade npm +first with `npm install -g npm@11` (npm 11 needs Node 22.9+), or use pnpm. +Already scaffolded? Upgrade, then run `npm install` in the project. +[Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install) +has the other fix. + + **pnpm and TypeScript versions only matter for the framework monorepo.** If you clone [`objectstack-ai/objectstack`](https://github.com/objectstack-ai/objectstack) diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx index 40aea0d81f8..e843f61fbac 100644 --- a/content/docs/getting-started/your-first-project.mdx +++ b/content/docs/getting-started/your-first-project.mdx @@ -28,6 +28,15 @@ That's all. A standalone project does **not** need pnpm, TypeScript pre-installe or a database server — the default template runs on an in-memory driver, and TypeScript comes in as a dev dependency. + +**npm 10 cannot install the CLI right now.** npm 10, the npm that Node 22 ships, +fails with `Cannot read properties of null (reading 'edgesOut')`. Upgrade npm +first with `npm install -g npm@11` (npm 11 needs Node 22.9+), or use pnpm. +Already scaffolded? Upgrade, then run `npm install` in the project. +[Troubleshooting](/docs/deployment/troubleshooting#cannot-read-properties-of-null-reading-edgesout-from-npm-install) +has the other fix. + + ## 1. Scaffold ```bash