sharp 0.32.6 → 0.33.0-alpha.3

package/README.md

@@ -16,7 +16,7 @@ Lanczos resampling ensures quality is not sacrificed for speed.
 As well as image resizing, operations such as
 rotation, extraction, compositing and gamma correction are available.
 
-Most modern macOS, Windows and Linux systems running Node.js >= 14.15.0
+Most modern macOS, Windows and Linux systems running Node.js >= 18.17.0
 do not require any additional install or runtime dependencies.
 
 ## Documentation

package/binding.gyp

@@ -1,8 +1,13 @@
+# Copyright 2013 Lovell Fuller and others.
+# SPDX-License-Identifier: Apache-2.0
+
 {
   'variables': {
     'vips_version': '<!(node -p "require(\'./lib/libvips\').minimumLibvipsVersion")',
-    'platform_and_arch': '<!(node -p "require(\'./lib/platform\')()")',
-    'sharp_vendor_dir': './vendor/<(vips_version)/<(platform_and_arch)'
+    'platform_and_arch': '<!(node -p "require(\'./lib/libvips\').buildPlatformArch()")',
+    'sharp_libvips_include_dir': '<!(node -p "require(\'./lib/libvips\').buildSharpLibvipsIncludeDir()")',
+    'sharp_libvips_cplusplus_dir': '<!(node -p "require(\'./lib/libvips\').buildSharpLibvipsCPlusPlusDir()")',
+    'sharp_libvips_lib_dir': '<!(node -p "require(\'./lib/libvips\').buildSharpLibvipsLibDir()")'
   },
   'targets': [{
     'target_name': 'libvips-cpp',
@@ -15,19 +20,19 @@
           '_ALLOW_KEYWORD_MACROS'
         ],
         'sources': [
-          'src/libvips/cplusplus/VConnection.cpp',
-          'src/libvips/cplusplus/VError.cpp',
-          'src/libvips/cplusplus/VImage.cpp',
-          'src/libvips/cplusplus/VInterpolate.cpp',
-          'src/libvips/cplusplus/VRegion.cpp'
+          '<(sharp_libvips_cplusplus_dir)/VConnection.cpp',
+          '<(sharp_libvips_cplusplus_dir)/VError.cpp',
+          '<(sharp_libvips_cplusplus_dir)/VImage.cpp',
+          '<(sharp_libvips_cplusplus_dir)/VInterpolate.cpp',
+          '<(sharp_libvips_cplusplus_dir)/VRegion.cpp'
         ],
         'include_dirs': [
-          '<(sharp_vendor_dir)/include',
-          '<(sharp_vendor_dir)/include/glib-2.0',
-          '<(sharp_vendor_dir)/lib/glib-2.0/include'
+          '<(sharp_libvips_include_dir)',
+          '<(sharp_libvips_include_dir)/glib-2.0',
+          '<(sharp_libvips_lib_dir)/glib-2.0/include'
         ],
         'link_settings': {
-          'library_dirs': ['<(sharp_vendor_dir)/lib'],
+          'library_dirs': ['<(sharp_libvips_lib_dir)'],
           'libraries': [
             'libvips.lib',
             'libglib-2.0.lib',
@@ -70,7 +75,7 @@
   }, {
     'target_name': 'sharp-<(platform_and_arch)',
     'defines': [
-      'NAPI_VERSION=7',
+      'NAPI_VERSION=9',
       'NODE_ADDON_API_DISABLE_DEPRECATED',
       'NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS'
     ],
@@ -79,7 +84,6 @@
       'libvips-cpp'
     ],
     'variables': {
-      'runtime_link%': 'shared',
       'conditions': [
         ['OS != "win"', {
           'pkg_config_path': '<!(node -p "require(\'./lib/libvips\').pkgConfigPath()")',
@@ -106,12 +110,8 @@
       ['use_global_libvips == "true"', {
         # Use pkg-config for include and lib
         'include_dirs': ['<!@(PKG_CONFIG_PATH="<(pkg_config_path)" pkg-config --cflags-only-I vips-cpp vips glib-2.0 | sed s\/-I//g)'],
+        'libraries': ['<!@(PKG_CONFIG_PATH="<(pkg_config_path)" pkg-config --libs vips-cpp)'],
         'conditions': [
-          ['runtime_link == "static"', {
-            'libraries': ['<!@(PKG_CONFIG_PATH="<(pkg_config_path)" pkg-config --libs --static vips-cpp)']
-          }, {
-            'libraries': ['<!@(PKG_CONFIG_PATH="<(pkg_config_path)" pkg-config --libs vips-cpp)']
-          }],
           ['OS == "linux"', {
             'defines': [
               # Inspect libvips-cpp.so to determine which C++11 ABI version was used and set _GLIBCXX_USE_CXX11_ABI accordingly. This is quite horrible.
@@ -122,9 +122,9 @@
       }, {
         # Use pre-built libvips stored locally within node_modules
         'include_dirs': [
-          '<(sharp_vendor_dir)/include',
-          '<(sharp_vendor_dir)/include/glib-2.0',
-          '<(sharp_vendor_dir)/lib/glib-2.0/include'
+          '<(sharp_libvips_include_dir)',
+          '<(sharp_libvips_include_dir)/glib-2.0',
+          '<(sharp_libvips_lib_dir)/glib-2.0/include'
         ],
         'conditions': [
           ['OS == "win"', {
@@ -133,7 +133,7 @@
               '_FILE_OFFSET_BITS=64'
             ],
             'link_settings': {
-              'library_dirs': ['<(sharp_vendor_dir)/lib'],
+              'library_dirs': ['<(sharp_libvips_lib_dir)'],
               'libraries': [
                 'libvips.lib',
                 'libglib-2.0.lib',
@@ -143,7 +143,9 @@
           }],
           ['OS == "mac"', {
             'link_settings': {
-              'library_dirs': ['../<(sharp_vendor_dir)/lib'],
+              'library_dirs': [
+                '<(sharp_libvips_lib_dir)'
+              ],
               'libraries': [
                 'libvips-cpp.42.dylib'
               ]
@@ -151,7 +153,9 @@
             'xcode_settings': {
               'OTHER_LDFLAGS': [
                 # Ensure runtime linking is relative to sharp.node
-                '-Wl,-rpath,\'@loader_path/../../<(sharp_vendor_dir)/lib\''
+                '-Wl,-rpath,\'@loader_path/../../sharp-libvips-<(platform_and_arch)/lib\'',
+                '-Wl,-rpath,\'@loader_path/../../node_modules/@sharpen/sharp-libvips-<(platform_and_arch)/lib\'',
+                '-Wl,-rpath,\'@loader_path/../../../node_modules/@sharpen/sharp-libvips-<(platform_and_arch)/lib\''
               ]
             }
           }],
@@ -160,13 +164,19 @@
               '_GLIBCXX_USE_CXX11_ABI=1'
             ],
             'link_settings': {
-              'library_dirs': ['../<(sharp_vendor_dir)/lib'],
+              'library_dirs': [
+                '<(sharp_libvips_lib_dir)'
+              ],
               'libraries': [
                 '-l:libvips-cpp.so.42'
               ],
               'ldflags': [
                 # Ensure runtime linking is relative to sharp.node
-                '-Wl,-s -Wl,--disable-new-dtags -Wl,-rpath=\'$$ORIGIN/../../<(sharp_vendor_dir)/lib\''
+                '-Wl,-s',
+                '-Wl,--disable-new-dtags',
+                '-Wl,-rpath=\'$$ORIGIN/../../sharp-libvips-<(platform_and_arch)/lib\'',
+                '-Wl,-rpath=\'$$ORIGIN/../../node_modules/@sharpen/sharp-libvips-<(platform_and_arch)/lib\'',
+                '-Wl,-rpath=\'$$ORIGIN/../../../node_modules/@sharpen/sharp-libvips-<(platform_and_arch)/lib\''
               ]
             }
           }]
@@ -232,5 +242,23 @@
         ]
       }
     },
+  }, {
+    'target_name': 'copy-dll',
+    'type': 'none',
+    'dependencies': [
+      'sharp-<(platform_and_arch)'
+    ],
+    'conditions': [
+      ['OS == "win"', {
+        'copies': [{
+          'destination': 'build/Release',
+          'files': [
+            '<(sharp_libvips_lib_dir)/libvips-42.dll',
+            '<(sharp_libvips_lib_dir)/libglib-2.0-0.dll',
+            '<(sharp_libvips_lib_dir)/libgobject-2.0-0.dll'
+          ]
+        }]
+      }]
+    ]
   }]
 }

package/install/check.js

@@ -0,0 +1,27 @@
+// Copyright 2013 Lovell Fuller and others.
+// SPDX-License-Identifier: Apache-2.0
+
+'use strict';
+
+const { useGlobalLibvips, globalLibvipsVersion, log, gypRebuild } = require('../lib/libvips');
+
+const buildFromSource = (msg) => {
+  log(msg);
+  log('Attempting to build from source via node-gyp');
+  try {
+    require('node-gyp');
+  } catch (err) {
+    log('You might need to install node-gyp');
+  }
+  log('See https://sharp.pixelplumbing.com/install#building-from-source');
+  const status = gypRebuild();
+  if (status !== 0) {
+    process.exit(status);
+  }
+};
+
+if (useGlobalLibvips()) {
+  buildFromSource(`Detected globally-installed libvips v${globalLibvipsVersion()}`);
+} else if (process.env.npm_config_build_from_source) {
+  buildFromSource('Detected --build-from-source flag');
+}

package/lib/constructor.js

@@ -3,11 +3,10 @@
 
 'use strict';
 
-const util = require('util');
-const stream = require('stream');
+const util = require('node:util');
+const stream = require('node:stream');
 const is = require('./is');
 
-require('./libvips').hasVendoredLibvips();
 require('./sharp');
 
 // Use NODE_DEBUG=sharp to enable libvips warnings

package/lib/index.d.ts

@@ -91,12 +91,6 @@ declare namespace sharp {
         zlib?: string | undefined;
     };
 
-    /** An Object containing the platform and architecture of the current and installed vendored binaries. */
-    const vendor: {
-        current: string;
-        installed: string[];
-    };
-
     /** An Object containing the available interpolators and their proper values */
     const interpolators: Interpolators;
 
@@ -705,7 +699,6 @@ declare namespace sharp {
 
         /**
          * Use these AVIF options for output image.
-         * Whilst it is possible to create AVIF images smaller than 16x16 pixels, most web browsers do not display these properly.
          * @param options Output options.
          * @throws {Error} Invalid options
          * @returns A sharp instance that can be used to chain operations

package/lib/is.js

@@ -138,18 +138,18 @@ const invalidParameterError = function (name, expected, actual) {
 };
 
 module.exports = {
-  defined: defined,
-  object: object,
-  plainObject: plainObject,
-  fn: fn,
-  bool: bool,
-  buffer: buffer,
-  typedArray: typedArray,
-  arrayBuffer: arrayBuffer,
-  string: string,
-  number: number,
-  integer: integer,
-  inRange: inRange,
-  inArray: inArray,
-  invalidParameterError: invalidParameterError
+  defined,
+  object,
+  plainObject,
+  fn,
+  bool,
+  buffer,
+  typedArray,
+  arrayBuffer,
+  string,
+  number,
+  integer,
+  inRange,
+  inArray,
+  invalidParameterError
 };

package/lib/libvips.js

@@ -3,61 +3,74 @@
 
 'use strict';
 
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-const spawnSync = require('child_process').spawnSync;
+const { spawnSync } = require('node:child_process');
 const semverCoerce = require('semver/functions/coerce');
 const semverGreaterThanOrEqualTo = require('semver/functions/gte');
+const detectLibc = require('detect-libc');
 
-const platform = require('./platform');
-const { config } = require('../package.json');
+const { engines } = require('../package.json');
 
-const env = process.env;
-const minimumLibvipsVersionLabelled = env.npm_package_config_libvips || /* istanbul ignore next */
-  config.libvips;
+const minimumLibvipsVersionLabelled = process.env.npm_package_config_libvips || /* istanbul ignore next */
+  engines.libvips;
 const minimumLibvipsVersion = semverCoerce(minimumLibvipsVersionLabelled).version;
 
+const prebuiltPlatforms = [
+  'darwin-arm64', 'darwin-x64',
+  'linux-arm', 'linux-arm64', 'linux-x64',
+  'linuxmusl-arm64', 'linuxmusl-x64',
+  'win32-ia32', 'win32-x64'
+];
+
 const spawnSyncOptions = {
   encoding: 'utf8',
   shell: true
 };
 
-const vendorPath = path.join(__dirname, '..', 'vendor', minimumLibvipsVersion, platform());
-
-const mkdirSync = function (dirPath) {
-  try {
-    fs.mkdirSync(dirPath, { recursive: true });
-  } catch (err) {
-    /* istanbul ignore next */
-    if (err.code !== 'EEXIST') {
-      throw err;
-    }
+const log = (item) => {
+  if (item instanceof Error) {
+    console.error(`sharp: Installation error: ${item.message}`);
+  } else {
+    console.log(`sharp: ${item}`);
   }
 };
 
-const cachePath = function () {
-  const npmCachePath = env.npm_config_cache || /* istanbul ignore next */
-    (env.APPDATA ? path.join(env.APPDATA, 'npm-cache') : path.join(os.homedir(), '.npm'));
-  mkdirSync(npmCachePath);
-  const libvipsCachePath = path.join(npmCachePath, '_libvips');
-  mkdirSync(libvipsCachePath);
-  return libvipsCachePath;
+/* istanbul ignore next */
+const runtimeLibc = () => detectLibc.isNonGlibcLinuxSync() ? detectLibc.familySync() : '';
+
+const runtimePlatformArch = () => `${process.platform}${runtimeLibc()}-${process.arch}`;
+
+/* istanbul ignore next */
+const buildPlatformArch = () => {
+  /* eslint camelcase: ["error", { allow: ["^npm_config_"] }] */
+  const { npm_config_arch, npm_config_platform, npm_config_libc } = process.env;
+  return `${npm_config_platform || process.platform}${npm_config_libc || runtimeLibc()}-${npm_config_arch || process.arch}`;
 };
 
-const integrity = function (platformAndArch) {
-  return env[`npm_package_config_integrity_${platformAndArch.replace('-', '_')}`] || config.integrity[platformAndArch];
+const buildSharpLibvipsIncludeDir = () => {
+  try {
+    return require('@sharpen/sharp-libvips-dev/include');
+  } catch {}
+  /* istanbul ignore next */
+  return '';
 };
 
-const log = function (item) {
-  if (item instanceof Error) {
-    console.error(`sharp: Installation error: ${item.message}`);
-  } else {
-    console.log(`sharp: ${item}`);
-  }
+const buildSharpLibvipsCPlusPlusDir = () => {
+  try {
+    return require('@sharpen/sharp-libvips-dev/cplusplus');
+  } catch {}
+  /* istanbul ignore next */
+  return '';
+};
+
+const buildSharpLibvipsLibDir = () => {
+  try {
+    return require(`@sharpen/sharp-libvips-${buildPlatformArch()}/lib`);
+  } catch {}
+  /* istanbul ignore next */
+  return '';
 };
 
-const isRosetta = function () {
+const isRosetta = () => {
   /* istanbul ignore next */
   if (process.platform === 'darwin' && process.arch === 'x64') {
     const translated = spawnSync('sysctl sysctl.proc_translated', spawnSyncOptions).stdout;
@@ -66,12 +79,19 @@ const isRosetta = function () {
   return false;
 };
 
-const globalLibvipsVersion = function () {
+/* istanbul ignore next */
+const gypRebuild = () =>
+  spawnSync('node-gyp rebuild', {
+    ...spawnSyncOptions,
+    stdio: 'inherit'
+  }).status;
+
+const globalLibvipsVersion = () => {
   if (process.platform !== 'win32') {
     const globalLibvipsVersion = spawnSync('pkg-config --modversion vips-cpp', {
       ...spawnSyncOptions,
       env: {
-        ...env,
+        ...process.env,
         PKG_CONFIG_PATH: pkgConfigPath()
       }
     }).stdout;
@@ -82,17 +102,8 @@ const globalLibvipsVersion = function () {
   }
 };
 
-const hasVendoredLibvips = function () {
-  return fs.existsSync(vendorPath);
-};
-
-/* istanbul ignore next */
-const removeVendoredLibvips = function () {
-  fs.rmSync(vendorPath, { recursive: true, maxRetries: 3, force: true });
-};
-
 /* istanbul ignore next */
-const pkgConfigPath = function () {
+const pkgConfigPath = () => {
   if (process.platform !== 'win32') {
     const brewPkgConfigPath = spawnSync(
       'which brew >/dev/null 2>&1 && brew environment --plain | grep PKG_CONFIG_LIBDIR | cut -d" " -f2',
@@ -100,7 +111,7 @@ const pkgConfigPath = function () {
     ).stdout || '';
     return [
       brewPkgConfigPath.trim(),
-      env.PKG_CONFIG_PATH,
+      process.env.PKG_CONFIG_PATH,
       '/usr/local/lib/pkgconfig',
       '/usr/lib/pkgconfig',
       '/usr/local/libdata/pkgconfig',
@@ -111,8 +122,9 @@ const pkgConfigPath = function () {
   }
 };
 
-const useGlobalLibvips = function () {
-  if (Boolean(env.SHARP_IGNORE_GLOBAL_LIBVIPS) === true) {
+const useGlobalLibvips = () => {
+  if (Boolean(process.env.SHARP_IGNORE_GLOBAL_LIBVIPS) === true) {
+    log('Detected SHARP_IGNORE_GLOBAL_LIBVIPS, skipping search for globally-installed libvips');
     return false;
   }
   /* istanbul ignore next */
@@ -127,14 +139,15 @@ const useGlobalLibvips = function () {
 
 module.exports = {
   minimumLibvipsVersion,
-  minimumLibvipsVersionLabelled,
-  cachePath,
-  integrity,
+  prebuiltPlatforms,
+  buildPlatformArch,
+  buildSharpLibvipsIncludeDir,
+  buildSharpLibvipsCPlusPlusDir,
+  buildSharpLibvipsLibDir,
+  runtimePlatformArch,
   log,
+  gypRebuild,
   globalLibvipsVersion,
-  hasVendoredLibvips,
-  removeVendoredLibvips,
   pkgConfigPath,
-  useGlobalLibvips,
-  mkdirSync
+  useGlobalLibvips
 };

package/lib/output.js

@@ -3,7 +3,7 @@
 
 'use strict';
 
-const path = require('path');
+const path = require('node:path');
 const is = require('./is');
 const sharp = require('./sharp');
 
@@ -867,9 +867,6 @@ function tiff (options) {
 /**
  * Use these AVIF options for output image.
  *
- * Whilst it is possible to create AVIF images smaller than 16x16 pixels,
- * most web browsers do not display these properly.
- *
  * AVIF image sequences are not supported.
  *
  * @example
@@ -909,9 +906,9 @@ function avif (options) {
  *
  * @since 0.23.0
  *
- * @param {Object} [options] - output options
+ * @param {Object} options - output options
+ * @param {string} options.compression - compression format: av1, hevc
  * @param {number} [options.quality=50] - quality, integer 1-100
- * @param {string} [options.compression='av1'] - compression format: av1, hevc
  * @param {boolean} [options.lossless=false] - use lossless compression
  * @param {number} [options.effort=4] - CPU effort, between 0 (fastest) and 9 (slowest)
  * @param {string} [options.chromaSubsampling='4:4:4'] - set to '4:2:0' to use chroma subsampling
@@ -920,6 +917,11 @@ function avif (options) {
  */
 function heif (options) {
   if (is.object(options)) {
+    if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
+      this.options.heifCompression = options.compression;
+    } else {
+      throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
+    }
     if (is.defined(options.quality)) {
       if (is.integer(options.quality) && is.inRange(options.quality, 1, 100)) {
         this.options.heifQuality = options.quality;
@@ -934,13 +936,6 @@ function heif (options) {
         throw is.invalidParameterError('lossless', 'boolean', options.lossless);
       }
     }
-    if (is.defined(options.compression)) {
-      if (is.string(options.compression) && is.inArray(options.compression, ['av1', 'hevc'])) {
-        this.options.heifCompression = options.compression;
-      } else {
-        throw is.invalidParameterError('compression', 'one of: av1, hevc', options.compression);
-      }
-    }
     if (is.defined(options.effort)) {
       if (is.integer(options.effort) && is.inRange(options.effort, 0, 9)) {
         this.options.heifEffort = options.effort;
@@ -955,6 +950,8 @@ function heif (options) {
         throw is.invalidParameterError('chromaSubsampling', 'one of: 4:2:0, 4:4:4', options.chromaSubsampling);
       }
     }
+  } else {
+    throw is.invalidParameterError('options', 'Object', options);
   }
   return this._updateFormatOut('heif', options);
 }
@@ -1370,7 +1367,7 @@ function _pipeline (callback) {
             reject(err);
           } else {
             if (this.options.resolveWithObject) {
-              resolve({ data: data, info: info });
+              resolve({ data, info });
             } else {
               resolve(data);
             }

package/lib/resize.js

@@ -250,6 +250,9 @@ function resize (widthOrOptions, height, options) {
   if (isResizeExpected(this.options)) {
     this.options.debuglog('ignoring previous resize options');
   }
+  if (this.options.widthPost !== -1) {
+    this.options.debuglog('operation order will be: extract, resize, extract');
+  }
   if (is.defined(widthOrOptions)) {
     if (is.object(widthOrOptions) && !is.defined(options)) {
       options = widthOrOptions;
@@ -437,7 +440,7 @@ function extend (extend) {
  *
  * - Use `extract` before `resize` for pre-resize extraction.
  * - Use `extract` after `resize` for post-resize extraction.
- * - Use `extract` before and after for both.
+ * - Use `extract` twice and `resize` once for extract-then-resize-then-extract in a fixed operation order.
  *
  * @example
  * sharp(input)

package/lib/sharp.js

@@ -3,36 +3,58 @@
 
 'use strict';
 
-const platformAndArch = require('./platform')();
+// Inspects the runtime environment and exports the relevant sharp.node binary
+
+const { familySync, versionSync } = require('detect-libc');
+
+const { runtimePlatformArch, prebuiltPlatforms, minimumLibvipsVersion } = require('./libvips');
+const runtimePlatform = runtimePlatformArch();
 
 /* istanbul ignore next */
 try {
-  module.exports = require(`../build/Release/sharp-${platformAndArch}.node`);
-} catch (err) {
-  // Bail early if bindings aren't available
-  const help = ['', 'Something went wrong installing the "sharp" module', '', err.message, '', 'Possible solutions:'];
-  if (/dylib/.test(err.message) && /Incompatible library version/.test(err.message)) {
-    help.push('- Update Homebrew: "brew update && brew upgrade vips"');
-  } else {
-    const [platform, arch] = platformAndArch.split('-');
-    if (platform === 'linux' && /Module did not self-register/.test(err.message)) {
-      help.push('- Using worker threads? See https://sharp.pixelplumbing.com/install#worker-threads');
+  // Check for local build
+  module.exports = require(`../build/Release/sharp-${runtimePlatform}.node`);
+} catch (errLocal) {
+  try {
+    // Check for runtime package
+    module.exports = require(`@sharpen/sharp-${runtimePlatform}/sharp.node`);
+  } catch (errPackage) {
+    const help = ['Could not load the "sharp" module at runtime'];
+    if (errLocal.code !== 'MODULE_NOT_FOUND') {
+      help.push(`${errLocal.code}: ${errLocal.message}`);
     }
-    help.push(
-      '- Install with verbose logging and look for errors: "npm install --ignore-scripts=false --foreground-scripts --verbose sharp"',
-      `- Install for the current ${platformAndArch} runtime: "npm install --platform=${platform} --arch=${arch} sharp"`
-    );
-  }
-  help.push(
-    '- Consult the installation documentation: https://sharp.pixelplumbing.com/install'
-  );
-  // Check loaded
-  if (process.platform === 'win32' || /symbol/.test(err.message)) {
-    const loadedModule = Object.keys(require.cache).find((i) => /[\\/]build[\\/]Release[\\/]sharp(.*)\.node$/.test(i));
-    if (loadedModule) {
-      const [, loadedPackage] = loadedModule.match(/node_modules[\\/]([^\\/]+)[\\/]/);
-      help.push(`- Ensure the version of sharp aligns with the ${loadedPackage} package: "npm ls sharp"`);
+    if (errPackage.code !== 'MODULE_NOT_FOUND') {
+      help.push(`${errPackage.code}: ${errPackage.message}`);
+    }
+    help.push('Possible solutions:');
+    // Common error messages
+    if (prebuiltPlatforms.includes(runtimePlatform)) {
+      help.push(`- Add an explicit dependency for the runtime platform: "npm install --force @sharpen/sharp-${runtimePlatform}"`);
+    } else {
+      help.push(`- The ${runtimePlatform} platform requires manual installation of libvips >= ${minimumLibvipsVersion}`);
+    }
+    if (runtimePlatform.startsWith('linux') && /symbol not found/i.test(errPackage)) {
+      try {
+        const { engines } = require(`@sharpen/sharp-libvips-${runtimePlatform}/package`);
+        const libcFound = `${familySync()} ${versionSync()}`;
+        const libcRequires = `${engines.musl ? 'musl' : 'glibc'} ${engines.musl || engines.glibc}`;
+        help.push(`- Update your OS: found ${libcFound}, requires ${libcRequires}`);
+      } catch (errEngines) {}
+    }
+    if (runtimePlatform.startsWith('darwin') && /Incompatible library version/.test(errLocal.message)) {
+      help.push('- Update Homebrew: "brew update && brew upgrade vips"');
+    }
+    if (errPackage.code === 'ERR_DLOPEN_DISABLED') {
+      help.push('- Run Node.js without using the --no-addons flag');
+    }
+    // Link to installation docs
+    if (runtimePlatform.startsWith('linux') && /Module did not self-register/.test(errLocal.message + errPackage.message)) {
+      help.push('- Using worker threads on Linux? See https://sharp.pixelplumbing.com/install#worker-threads');
+    } else if (runtimePlatform.startsWith('win32') && /The specified procedure could not be found/.test(errPackage.message)) {
+      help.push('- Using the canvas package on Windows? See https://sharp.pixelplumbing.com/install#canvas-and-windows');
+    } else {
+      help.push('- Consult the installation documentation: https://sharp.pixelplumbing.com/install');
     }
+    throw new Error(help.join('\n'));
   }
-  throw new Error(help.join('\n'));
 }