From 3a0c37569219d10321f559fc63715ef45aca0c0d Mon Sep 17 00:00:00 2001
From: Lovell Fuller <github@lovell.info>
Date: Wed, 13 Dec 2023 12:59:14 +0000
Subject: [PATCH] Docs: improve cross-platform help messaging

tldr; don't use npm for multi-platform installs
---
 .github/ISSUE_TEMPLATE/installation.md |  7 +++++--
 docs/install.md                        | 16 ++++++++++++----
 lib/sharp.js                           |  7 +++----
 3 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/.github/ISSUE_TEMPLATE/installation.md b/.github/ISSUE_TEMPLATE/installation.md
index 4f9e831a..920bdf5e 100644
--- a/.github/ISSUE_TEMPLATE/installation.md
+++ b/.github/ISSUE_TEMPLATE/installation.md
@@ -11,7 +11,10 @@ labels: installation
 
 <!-- Please place an [x] in the box to confirm. -->
 
-- [ ] I have read the [documentation relating to installation](https://sharp.pixelplumbing.com/install).
+- [ ] I have read and understood all of the [documentation relating to installation](https://sharp.pixelplumbing.com/install).
+- [ ] I have searched for known bugs relating to this problem in my choice of package manager.
+
+You must confirm both of these before continuing.
 
 ### Are you using the latest version of sharp?
 
@@ -47,7 +50,7 @@ and try again before opening an issue.
 
 If you cannot confirm any of these,
 please upgrade to the latest version of your chosen package manager
-and ensure you are allowing the installation of optional dependencies
+and ensure you are allowing the installation of optional or multi-platform dependencies
 before opening an issue.
 
 ### What is the complete output of running `npm install --verbose --foreground-scripts sharp` in an empty directory?
diff --git a/docs/install.md b/docs/install.md
index 1350ace6..f1b8c3ca 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -4,6 +4,10 @@ Works with your choice of JavaScript package manager.
 
 > ⚠️  **Please ensure your package manager is configured to install optional dependencies**
 
+If a package manager lockfile must support multiple platforms,
+please see the [cross-platform](#cross-platform) section
+to help decide which package manager is appropriate.
+
 ```sh
 npm install sharp
 ```
@@ -51,17 +55,21 @@ JPEG, PNG, WebP, AVIF (limited to 8-bit depth), TIFF, GIF and SVG (input) image
 
 ## Cross-platform
 
-At install time, package managers will automatically select prebuilt binaries for the current OS platform and CPU architecture, where available.
+At install time, package managers will automatically select prebuilt binaries
+for the current OS platform and CPU architecture, where available.
 
-Some package managers support multiple platforms and architectures within the same installation tree.
+Some package managers support multiple platforms and architectures
+within the same installation tree and/or using the same lockfile.
 
 ### npm
 
-Use the `--os`, `--cpu` and `--libc` flags:
+> ⚠️ **npm `package-lock.json` files can cause installation problems due to [npm bug #4828](https://github.com/npm/cli/issues/4828)**
+
+Provides limited support via `--os`, `--cpu` and `--libc` flags.
 
 Example to support both Intel and ARM CPUs on macOS:
 ```sh
-npm install --cpu=x64 --os=darwin  sharp
+npm install --cpu=x64 --os=darwin sharp
 npm install --cpu=arm64 --os=darwin sharp
 ```
 
diff --git a/lib/sharp.js b/lib/sharp.js
index c7d348d7..f0eb565e 100644
--- a/lib/sharp.js
+++ b/lib/sharp.js
@@ -49,11 +49,11 @@ if (sharp) {
     help.push(
       '- Ensure optional dependencies can be installed:',
       '    npm install --include=optional sharp',
-      '  or',
       '    yarn add sharp --ignore-engines',
+      '- Ensure your package manager supports multi-platform installation:',
+      '    See https://sharp.pixelplumbing.com/install#cross-platform',
       '- Add platform-specific dependencies:',
       `    npm install --os=${os} --cpu=${cpu} sharp`,
-      '  or',
       `    npm install --force @img/sharp-${runtimePlatform}`
     );
   } else {
@@ -61,7 +61,6 @@ if (sharp) {
       `- Manually install libvips >= ${minimumLibvipsVersion}`,
       '- Add experimental WebAssembly-based dependencies:',
       '    npm install --cpu=wasm32 sharp',
-      '  or',
       '    npm install --force @img/sharp-wasm32'
     );
   }
@@ -103,7 +102,7 @@ if (sharp) {
   }
   help.push(
     '- Consult the installation documentation:',
-    '    https://sharp.pixelplumbing.com/install'
+    '    See https://sharp.pixelplumbing.com/install'
   );
   throw new Error(help.join('\n'));
 }