From 2ca712b993740332eae547b4200d48ad95f74706 Mon Sep 17 00:00:00 2001 From: willbot Date: Wed, 7 Oct 2026 18:18:09 +0200 Subject: [PATCH 1/4] docs(docs): install the prisma dev dependency right after prisma init `prisma init` adds `prisma` to devDependencies and writes a prisma.config.ts that imports `prisma/config`, but it installs nothing. The Composer getting-started page ran `init` and moved on, so the next `npx prisma dev module.ts` stopped at CLI.CONFIG_UNREADABLE. The getting-started nightly has failed at that step every night since at least 2026-10-04. Add `npm install` after `init` on the Composer getting-started page, and update the init reference and the Compute getting-started page to say that `init` adds the dependency without installing it. Co-Authored-By: Claude Opus 5.5 Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/content/docs/cli/init.mdx | 14 +++++++++----- .../docs/content/docs/composer/getting-started.mdx | 5 ++++- apps/docs/content/docs/compute/getting-started.mdx | 2 +- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/apps/docs/content/docs/cli/init.mdx b/apps/docs/content/docs/cli/init.mdx index 5fc9b7d573c..fb8858d6ec9 100644 --- a/apps/docs/content/docs/cli/init.mdx +++ b/apps/docs/content/docs/cli/init.mdx @@ -8,11 +8,12 @@ metaDescription: Learn how prisma init prepares a repository for Prisma developm `init` prepares the current directory for Prisma development. It runs locally and calls no platform API. It does not scaffold the ORM: use [`orm init`](/cli/orm-init) to add the Prisma ORM config, contract, and runtime files to a project. -`init` does three things: +`init` does four things: 1. Adds a `postinstall` script to `package.json` (`prisma skills sync || exit 0`), so the [Prisma agent skills](/cli/skills) resync on every install and upgrade. -2. Scaffolds a `prisma.config.ts` recording which agents to install skills for, in the [`skills` config section](/cli/configuration#agent-skills). -3. Runs [`skills sync`](/cli/skills) once. +2. Adds `prisma` to `devDependencies` in `package.json`, pinned to the CLI's version. It does not install it. +3. Scaffolds a `prisma.config.ts` recording which agents to install skills for, in the [`skills` config section](/cli/configuration#agent-skills). +4. Runs [`skills sync`](/cli/skills) once. It never prompts, always exits 0, and is safe to rerun: each step reports what is already done. A `prisma.config.ts` or `postinstall` script that already exists is never edited. If `package.json` already has a different `postinstall` script, `init` reports it and tells you what to append instead of chaining or replacing it. @@ -20,8 +21,11 @@ It never prompts, always exits 0, and is safe to rerun: each step reports what i ```npm npx prisma@latest init +npm install ``` +Run the install straight after `init`, so the `prisma` package it added is in `node_modules`. + ## Options | Option | What it does | @@ -52,6 +56,6 @@ export default definePrismaConfig({ }); ``` -The `prisma/config` import resolves from your project's `node_modules`, so add `prisma` as a dev dependency before running other commands against this file. See [Configuration](/cli/configuration). +The `prisma/config` import resolves from your project's `node_modules`. Until you install the `prisma` dev dependency that `init` added, commands that read this file stop at `CLI.CONFIG_UNREADABLE`. See [Configuration](/cli/configuration). -Only `init` writes the `postinstall` hook. No other command edits `package.json`; [`skills sync`](/cli/skills) itself never touches it. +Only `init` writes the `postinstall` hook and the `prisma` dev dependency. No other command edits `package.json`; [`skills sync`](/cli/skills) itself never touches it. diff --git a/apps/docs/content/docs/composer/getting-started.mdx b/apps/docs/content/docs/composer/getting-started.mdx index 136eba43cdf..13f09ddb4f5 100644 --- a/apps/docs/content/docs/composer/getting-started.mdx +++ b/apps/docs/content/docs/composer/getting-started.mdx @@ -12,12 +12,15 @@ The app is deliberately tiny, with no database, so you can see the whole shape a :::note[Working with a coding agent] -Add the Composer skill first, even if you plan to write every line yourself. It ships inside the `@prisma/composer` package, and one command, run after step 1 installs the packages, copies it into the directories your agent reads and stops the agent from inventing an API that does not exist: +Add the Composer skill first, even if you plan to write every line yourself. It ships inside the `@prisma/composer` package, and one command, run after step 1 installs the packages, copies it into the directories your agent reads and stops the agent from inventing an API that does not exist. `init` adds `prisma` to your dev dependencies without installing it, so install straight after: ```npm npx prisma@latest init +npm install ``` +Without that install, later `prisma` commands stop at `CLI.CONFIG_UNREADABLE`, because the `prisma.config.ts` that `init` writes imports `prisma/config`. + `init` also adds a `postinstall` hook that keeps the skill matching the installed version; see [`skills`](/cli/skills). ::: diff --git a/apps/docs/content/docs/compute/getting-started.mdx b/apps/docs/content/docs/compute/getting-started.mdx index 36dd924ec52..3975515e046 100644 --- a/apps/docs/content/docs/compute/getting-started.mdx +++ b/apps/docs/content/docs/compute/getting-started.mdx @@ -134,7 +134,7 @@ If a coding agent does your deploying, install the Prisma Compute agent skill in npx skills add prisma/skills --skill prisma-compute ``` -The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`npx prisma@latest init`](/cli/init) once. It syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. +The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`npx prisma@latest init`](/cli/init) once, then install the `prisma` dev dependency it adds. It syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. ### Structured output From 28a612f1543d2fc3ad0bcca674aec306b35bf61b Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 8 Oct 2026 19:06:39 +0200 Subject: [PATCH 2/4] docs(compute): show the install after prisma init Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/content/docs/compute/getting-started.mdx | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/apps/docs/content/docs/compute/getting-started.mdx b/apps/docs/content/docs/compute/getting-started.mdx index 3975515e046..c91b882e012 100644 --- a/apps/docs/content/docs/compute/getting-started.mdx +++ b/apps/docs/content/docs/compute/getting-started.mdx @@ -134,7 +134,14 @@ If a coding agent does your deploying, install the Prisma Compute agent skill in npx skills add prisma/skills --skill prisma-compute ``` -The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`npx prisma@latest init`](/cli/init) once, then install the `prisma` dev dependency it adds. It syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. +The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`init`](/cli/init) once, then install the `prisma` dev dependency it adds: + +```npm +npx prisma@latest init +npm install +``` + +`init` syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. ### Structured output From ad35ca5abdc1f4cdce45276f80c4af88651683fc Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 8 Oct 2026 19:42:30 +0200 Subject: [PATCH 3/4] docs(composer): install prisma@latest so npm 10 does not crash Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/content/docs/composer/getting-started.mdx | 4 +++- apps/docs/content/docs/composer/porting-an-app.mdx | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/docs/composer/getting-started.mdx b/apps/docs/content/docs/composer/getting-started.mdx index fbb5a734c68..89e9cf714cc 100644 --- a/apps/docs/content/docs/composer/getting-started.mdx +++ b/apps/docs/content/docs/composer/getting-started.mdx @@ -41,9 +41,11 @@ Create a directory and install the two Composer packages, plus [arktype](https:/ npm init -y npm pkg set type=module npm install @prisma/composer @prisma/composer-prisma-cloud arktype -npm install -D typescript @types/bun prisma +npm install -D typescript @types/bun prisma@latest ``` +Name `prisma@latest`, not a bare `prisma`: with a bare name, npm 10 (the npm that ships with Node.js 22) can stop with `Cannot read properties of null (reading 'edgesOut')`. + `"type": "module"` matters: Composer loads your entry file as an ES module, and without it every Composer command stops at `COMPOSE.ENTRY_UNLOADABLE` ("Cannot use import statement outside a module"). You do not need to pin `effect` yourself. `@prisma/composer` and `@prisma/composer-prisma-cloud` pin every `effect`-family package their deploy engine needs, so a fresh install resolves a single copy. A conflict only appears when something in your dependency tree, your own `effect` pin or another dependency's, hoists a different `effect` where the deploy engine resolves it. The CLI then cannot evaluate `prisma.config.ts` and stops with `CLI.CONFIG_UNREADABLE`; see [When prisma.config.ts fails on an effect version conflict](/composer/deploying#when-prismaconfigts-fails-on-an-effect-version-conflict). diff --git a/apps/docs/content/docs/composer/porting-an-app.mdx b/apps/docs/content/docs/composer/porting-an-app.mdx index 844bb114346..241cdd60f8c 100644 --- a/apps/docs/content/docs/composer/porting-an-app.mdx +++ b/apps/docs/content/docs/composer/porting-an-app.mdx @@ -64,10 +64,10 @@ export default compute({ export default { output: 'standalone' }; ``` -`prisma.config.ts` imports `prisma/config`, which resolves from your project's `node_modules`, so install the Prisma CLI as a dev dependency if the project does not have it yet: +`prisma.config.ts` imports `prisma/config`, which resolves from your project's `node_modules`, so install the Prisma CLI as a dev dependency if the project does not have it yet. Name `prisma@latest`; with a bare `prisma`, npm 10 can stop with `Cannot read properties of null (reading 'edgesOut')`: ```npm -npm install -D prisma +npm install -D prisma@latest ``` Then add `nextjsBuild()` from `@prisma/composer/nextjs/control` to the `extensions` of the `composer` section in `prisma.config.ts`: From 885a351b42517c9da886fed88324775d83fb102d Mon Sep 17 00:00:00 2001 From: willbot Date: Thu, 8 Oct 2026 20:09:48 +0200 Subject: [PATCH 4/4] docs(cli): say init leaves an existing prisma entry, install after init on the CLI index Revert the prisma@latest workaround and the Composer note's install: step 1 already installs prisma, and the npm 10 crash is a Composer dependency bug being fixed upstream. Revert the Compute page: its Composer app already installs prisma. Signed-off-by: willbot Signed-off-by: Will Madden --- apps/docs/content/docs/cli/index.mdx | 3 ++- apps/docs/content/docs/cli/init.mdx | 12 ++++++------ apps/docs/content/docs/composer/getting-started.mdx | 9 ++------- apps/docs/content/docs/composer/porting-an-app.mdx | 4 ++-- apps/docs/content/docs/compute/getting-started.mdx | 9 +-------- 5 files changed, 13 insertions(+), 24 deletions(-) diff --git a/apps/docs/content/docs/cli/index.mdx b/apps/docs/content/docs/cli/index.mdx index f6ed145b7b6..742dd54d602 100644 --- a/apps/docs/content/docs/cli/index.mdx +++ b/apps/docs/content/docs/cli/index.mdx @@ -102,10 +102,11 @@ Plain `db migrate` never moves a ref; `--advance-ref db` is what keeps the next ## Agent skills -Prisma packages ship [agent skills](/ai/tools/skills): instructions that teach AI coding agents the installed version's commands and APIs. [`init`](/cli/init) prepares a repository once, and [`skills sync`](/cli/skills) keeps the installed copies matching your package versions. +Prisma packages ship [agent skills](/ai/tools/skills): instructions that teach AI coding agents the installed version's commands and APIs. [`init`](/cli/init) prepares a repository once, and [`skills sync`](/cli/skills) keeps the installed copies matching your package versions. Install after `init`, so the `prisma` dev dependency it adds is in `node_modules`: ```npm npx prisma@latest init +npm install npx prisma skills sync ``` diff --git a/apps/docs/content/docs/cli/init.mdx b/apps/docs/content/docs/cli/init.mdx index fb8858d6ec9..1b507242c93 100644 --- a/apps/docs/content/docs/cli/init.mdx +++ b/apps/docs/content/docs/cli/init.mdx @@ -3,7 +3,7 @@ title: init description: Prepare a repository for Prisma development. url: /cli/init metaTitle: init | Prisma CLI -metaDescription: Learn how prisma init prepares a repository for Prisma development with a skills-sync postinstall hook and a scaffolded prisma.config.ts. +metaDescription: Learn how prisma init prepares a repository for Prisma development with a skills-sync postinstall hook, a prisma dev dependency, and a scaffolded prisma.config.ts. --- `init` prepares the current directory for Prisma development. It runs locally and calls no platform API. It does not scaffold the ORM: use [`orm init`](/cli/orm-init) to add the Prisma ORM config, contract, and runtime files to a project. @@ -11,11 +11,11 @@ metaDescription: Learn how prisma init prepares a repository for Prisma developm `init` does four things: 1. Adds a `postinstall` script to `package.json` (`prisma skills sync || exit 0`), so the [Prisma agent skills](/cli/skills) resync on every install and upgrade. -2. Adds `prisma` to `devDependencies` in `package.json`, pinned to the CLI's version. It does not install it. +2. Adds `prisma` to `devDependencies` in `package.json`, pinned to the CLI's version, unless it is already listed. It does not install it. 3. Scaffolds a `prisma.config.ts` recording which agents to install skills for, in the [`skills` config section](/cli/configuration#agent-skills). 4. Runs [`skills sync`](/cli/skills) once. -It never prompts, always exits 0, and is safe to rerun: each step reports what is already done. A `prisma.config.ts` or `postinstall` script that already exists is never edited. If `package.json` already has a different `postinstall` script, `init` reports it and tells you what to append instead of chaining or replacing it. +It never prompts, always exits 0, and is safe to rerun: each step reports what is already done. A `prisma.config.ts`, `postinstall` script, or `prisma` entry that already exists is never edited. If `package.json` already has a different `postinstall` script, `init` reports it and tells you what to append instead of chaining or replacing it. ## Usage @@ -24,7 +24,7 @@ npx prisma@latest init npm install ``` -Run the install straight after `init`, so the `prisma` package it added is in `node_modules`. +If `init` added `prisma`, run the install straight after, so the package is in `node_modules`. ## Options @@ -56,6 +56,6 @@ export default definePrismaConfig({ }); ``` -The `prisma/config` import resolves from your project's `node_modules`. Until you install the `prisma` dev dependency that `init` added, commands that read this file stop at `CLI.CONFIG_UNREADABLE`. See [Configuration](/cli/configuration). +The `prisma/config` import resolves from your project's `node_modules`. Until `prisma` is installed, commands that read this file stop at `CLI.CONFIG_UNREADABLE`. See [Configuration](/cli/configuration). -Only `init` writes the `postinstall` hook and the `prisma` dev dependency. No other command edits `package.json`; [`skills sync`](/cli/skills) itself never touches it. +Only `init` writes the `postinstall` hook. [`orm init`](/cli/orm-init) also adds `prisma` to `devDependencies`. [`skills sync`](/cli/skills) never touches `package.json`. diff --git a/apps/docs/content/docs/composer/getting-started.mdx b/apps/docs/content/docs/composer/getting-started.mdx index 89e9cf714cc..b72d3df73d2 100644 --- a/apps/docs/content/docs/composer/getting-started.mdx +++ b/apps/docs/content/docs/composer/getting-started.mdx @@ -12,15 +12,12 @@ The app is deliberately tiny, with no database, so you can see the whole shape a :::note[Working with a coding agent] -Add the Composer skill first, even if you plan to write every line yourself. It ships inside the `@prisma/composer` package, and one command, run after step 1 installs the packages, copies it into the directories your agent reads and stops the agent from inventing an API that does not exist. `init` adds `prisma` to your dev dependencies without installing it, so install straight after: +Add the Composer skill first, even if you plan to write every line yourself. It ships inside the `@prisma/composer` package, and one command, run after step 1 installs the packages, copies it into the directories your agent reads and stops the agent from inventing an API that does not exist: ```npm npx prisma@latest init -npm install ``` -Without that install, later `prisma` commands stop at `CLI.CONFIG_UNREADABLE`, because the `prisma.config.ts` that `init` writes imports `prisma/config`. - `init` also adds a `postinstall` hook that keeps the skill matching the installed version; see [`skills`](/cli/skills). ::: @@ -41,11 +38,9 @@ Create a directory and install the two Composer packages, plus [arktype](https:/ npm init -y npm pkg set type=module npm install @prisma/composer @prisma/composer-prisma-cloud arktype -npm install -D typescript @types/bun prisma@latest +npm install -D typescript @types/bun prisma ``` -Name `prisma@latest`, not a bare `prisma`: with a bare name, npm 10 (the npm that ships with Node.js 22) can stop with `Cannot read properties of null (reading 'edgesOut')`. - `"type": "module"` matters: Composer loads your entry file as an ES module, and without it every Composer command stops at `COMPOSE.ENTRY_UNLOADABLE` ("Cannot use import statement outside a module"). You do not need to pin `effect` yourself. `@prisma/composer` and `@prisma/composer-prisma-cloud` pin every `effect`-family package their deploy engine needs, so a fresh install resolves a single copy. A conflict only appears when something in your dependency tree, your own `effect` pin or another dependency's, hoists a different `effect` where the deploy engine resolves it. The CLI then cannot evaluate `prisma.config.ts` and stops with `CLI.CONFIG_UNREADABLE`; see [When prisma.config.ts fails on an effect version conflict](/composer/deploying#when-prismaconfigts-fails-on-an-effect-version-conflict). diff --git a/apps/docs/content/docs/composer/porting-an-app.mdx b/apps/docs/content/docs/composer/porting-an-app.mdx index 241cdd60f8c..844bb114346 100644 --- a/apps/docs/content/docs/composer/porting-an-app.mdx +++ b/apps/docs/content/docs/composer/porting-an-app.mdx @@ -64,10 +64,10 @@ export default compute({ export default { output: 'standalone' }; ``` -`prisma.config.ts` imports `prisma/config`, which resolves from your project's `node_modules`, so install the Prisma CLI as a dev dependency if the project does not have it yet. Name `prisma@latest`; with a bare `prisma`, npm 10 can stop with `Cannot read properties of null (reading 'edgesOut')`: +`prisma.config.ts` imports `prisma/config`, which resolves from your project's `node_modules`, so install the Prisma CLI as a dev dependency if the project does not have it yet: ```npm -npm install -D prisma@latest +npm install -D prisma ``` Then add `nextjsBuild()` from `@prisma/composer/nextjs/control` to the `extensions` of the `composer` section in `prisma.config.ts`: diff --git a/apps/docs/content/docs/compute/getting-started.mdx b/apps/docs/content/docs/compute/getting-started.mdx index 7041c25f5b2..cd6c4e3fa3d 100644 --- a/apps/docs/content/docs/compute/getting-started.mdx +++ b/apps/docs/content/docs/compute/getting-started.mdx @@ -134,14 +134,7 @@ If a coding agent does your deploying, install the Prisma Compute agent skill in npx skills add prisma/skills --skill prisma-compute ``` -The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`init`](/cli/init) once, then install the `prisma` dev dependency it adds: - -```npm -npx prisma@latest init -npm install -``` - -`init` syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. +The `prisma-compute` skill teaches your agent the Compute workflow (auth, config, deploys, logs, and domains), so it follows the right steps. Supported agents pick it up automatically. See [Agent Skills](/ai/tools/skills) for the full catalog. For a Composer app, also run [`npx prisma@latest init`](/cli/init) once. It syncs the Composer skill that ships inside `@prisma/composer` and keeps it matching the installed version; that package-shipped set is what the CLI's own [`skills` commands](/cli/skills) manage. ### Structured output