Add infrastructure to build and publish as wasm32

Co-authored-by: Ingvar Stepanyan <me@rreverser.com>

.github/workflows/ci.yml

@@ -161,6 +161,37 @@ jobs:
             npm install --ignore-scripts
             npx mocha --no-config --spec=test/unit/io.js --timeout=30000
             [[ -n $prebuild_upload ]] && cd src && ln -s ../package.json && npx prebuild || true
+  github-runner-emscripten:
+    permissions:
+      contents: write
+    name: wasm32 - prebuild
+    runs-on: ubuntu-22.04
+    container: "emscripten/emsdk:3.1.48"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Dependencies
+        run: apt-get update && apt-get install -y pkg-config
+      - name: Dependencies (Node.js)
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+      - name: Install
+        run: emmake npm install --build-from-source
+      - name: Test
+        run: emmake npm test
+      - name: Test packaging
+        run: |
+          emmake npm run package-from-local-build
+          npm pkg set "optionalDependencies.@img/sharp-wasm32=file:./npm/wasm32"
+          npm run clean
+          npm install --cpu=wasm32
+          npm test
+      - name: Prebuild
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          prebuild_upload: ${{ secrets.GITHUB_TOKEN }}
+        run: cd src && ln -s ../package.json && emmake npx prebuild
   macstadium-runner:
     permissions:
       contents: write

docs/install.md

@@ -78,6 +78,15 @@ For cross-compiling, the `--platform`, `--arch` and `--libc` npm flags
 (or the `npm_config_platform`, `npm_config_arch` and `npm_config_libc` environment variables)
 can be used to configure the target environment.
 
+## WebAssembly
+
+Experimental support is provided for runtime environments that provide
+multi-threaded Wasm via Workers.
+
+```sh
+npm install --cpu=wasm32 sharp
+```
+
 ## FreeBSD
 
 The `vips` package must be installed before `npm install` is run.
@@ -118,11 +127,11 @@ When building your deployment package on a machine that differs from the target
 you will need to install either `@img/sharp-linux-x64` or `@img/sharp-linux-arm64` package.
 
 ```sh
-npm install --os=linux --cpu=x64
+npm install --os=linux --cpu=x64 sharp
 ```
 
 ```sh
-npm install --os=linux --cpu=arm64
+npm install --os=linux --cpu=arm64 sharp
 ```
 
 When using npm 9 or earlier, this can be achieved using the following:

lib/libvips.js

@@ -41,15 +41,23 @@ const runtimePlatformArch = () => `${process.platform}${runtimeLibc()}-${process
 
 /* istanbul ignore next */
 const buildPlatformArch = () => {
+  if (isEmscripten()) {
+    return 'wasm32';
+  }
   /* 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 libc = typeof npm_config_libc === 'string' ? npm_config_libc : runtimeLibc();
+  return `${npm_config_platform || process.platform}${libc}-${npm_config_arch || process.arch}`;
 };
 
 const buildSharpLibvipsIncludeDir = () => {
   try {
-    return require('@img/sharp-libvips-dev/include');
-  } catch {}
+    return require(`@img/sharp-libvips-dev-${buildPlatformArch()}/include`);
+  } catch {
+    try {
+      return require('@img/sharp-libvips-dev/include');
+    } catch {}
+  }
   /* istanbul ignore next */
   return '';
 };
@@ -64,12 +72,22 @@ const buildSharpLibvipsCPlusPlusDir = () => {
 
 const buildSharpLibvipsLibDir = () => {
   try {
-    return require(`@img/sharp-libvips-${buildPlatformArch()}/lib`);
-  } catch {}
+    return require(`@img/sharp-libvips-dev-${buildPlatformArch()}/lib`);
+  } catch {
+    try {
+      return require(`@img/sharp-libvips-${buildPlatformArch()}/lib`);
+    } catch {}
+  }
   /* istanbul ignore next */
   return '';
 };
 
+/* istanbul ignore next */
+const isEmscripten = () => {
+  const { CC } = process.env;
+  return Boolean(CC && CC.endsWith('/emcc'));
+};
+
 const isRosetta = () => {
   /* istanbul ignore next */
   if (process.platform === 'darwin' && process.arch === 'x64') {
@@ -81,7 +99,7 @@ const isRosetta = () => {
 
 /* istanbul ignore next */
 const spawnRebuild = () =>
-  spawnSync('node-gyp rebuild --directory=src', {
+  spawnSync(`node-gyp rebuild --directory=src ${isEmscripten() ? '--nodedir=emscripten' : ''}`, {
     ...spawnSyncOptions,
     stdio: 'inherit'
   }).status;

lib/sharp.js

@@ -9,62 +9,74 @@ const { familySync, versionSync } = require('detect-libc');
 
 const { runtimePlatformArch, prebuiltPlatforms, minimumLibvipsVersion } = require('./libvips');
 const runtimePlatform = runtimePlatformArch();
-const [isLinux, isMacOs, isWindows] = ['linux', 'darwin', 'win32'].map(os => runtimePlatform.startsWith(os));
 
-/* istanbul ignore next */
-try {
-  // Check for local build
-  module.exports = require(`../src/build/Release/sharp-${runtimePlatform}.node`);
-} catch (errLocal) {
+const paths = [
+  `../src/build/Release/sharp-${runtimePlatform}.node`,
+  '../src/build/Release/sharp-wasm32.node',
+  `@img/sharp-${runtimePlatform}/sharp.node`,
+  '@img/sharp-wasm32/sharp.node'
+];
+
+const errors = [];
+for (const path of paths) {
   try {
-    // Check for runtime package
-    module.exports = require(`@img/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}`);
-    }
-    if (errPackage.code !== 'MODULE_NOT_FOUND') {
-      help.push(`${errPackage.code}: ${errPackage.message}`);
-    }
-    help.push('Possible solutions:');
-    // Common error messages
-    if (prebuiltPlatforms.includes(runtimePlatform)) {
-      const [os, cpu] = runtimePlatform.split('-');
-      help.push('- Add an explicit dependency for the runtime platform:');
-      help.push(`    npm install --os=${os} --cpu=${cpu} sharp`);
-      help.push('  or');
-      help.push(`    npm install --force @img/sharp-${runtimePlatform}`);
-    } else {
-      help.push(`- The ${runtimePlatform} platform requires manual installation of libvips >= ${minimumLibvipsVersion}`);
-    }
-    if (isLinux && /symbol not found/i.test(errPackage)) {
-      try {
-        const { engines } = require(`@img/sharp-libvips-${runtimePlatform}/package`);
-        const libcFound = `${familySync()} ${versionSync()}`;
-        const libcRequires = `${engines.musl ? 'musl' : 'glibc'} ${engines.musl || engines.glibc}`;
-        help.push('- Update your OS:');
-        help.push(`    Found ${libcFound}`);
-        help.push(`    Requires ${libcRequires}`);
-      } catch (errEngines) {}
-    }
-    if (isMacOs && /Incompatible library version/.test(errLocal.message)) {
-      help.push('- Update Homebrew:');
-      help.push('    brew update && brew upgrade vips');
-    }
-    if (errPackage.code === 'ERR_DLOPEN_DISABLED') {
-      help.push('- Run Node.js without using the --no-addons flag');
-    }
-    if (process.versions.pnp) {
-      help.push('- Use a supported yarn linker, either pnpm or node-modules:');
-      help.push('    yarn config set nodeLinker node-modules');
-    }
-    // Link to installation docs
-    if (isWindows && /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');
+    module.exports = require(path);
+    break;
+  } catch (err) {
+    errors.push(err);
+  }
+}
+
+/* istanbul ignore next */
+if (!module.exports) {
+  const [isLinux, isMacOs, isWindows] = ['linux', 'darwin', 'win32'].map(os => runtimePlatform.startsWith(os));
+
+  const help = [`Could not load the "sharp" module using the ${runtimePlatform} runtime`];
+  errors.forEach(err => {
+    if (err.code !== 'MODULE_NOT_FOUND') {
+      help.push(`${err.code}: ${err.message}`);
     }
-    throw new Error(help.join('\n'));
+  });
+  const messages = errors.map(err => err.message).join(' ');
+  help.push('Possible solutions:');
+  // Common error messages
+  if (prebuiltPlatforms.includes(runtimePlatform)) {
+    const [os, cpu] = runtimePlatform.split('-');
+    help.push('- Add platform-specific dependencies:');
+    help.push(`    npm install --os=${os} --cpu=${cpu} sharp`);
+    help.push('  or');
+    help.push(`    npm install --force @img/sharp-${runtimePlatform}`);
+  } else {
+    help.push(`- Manually install libvips >= ${minimumLibvipsVersion}`);
+    help.push('- Add experimental WebAssembly-based dependencies:');
+    help.push('    npm install --cpu=wasm32 sharp');
+  }
+  if (isLinux && /symbol not found/i.test(messages)) {
+    try {
+      const { engines } = require(`@img/sharp-libvips-${runtimePlatform}/package`);
+      const libcFound = `${familySync()} ${versionSync()}`;
+      const libcRequires = `${engines.musl ? 'musl' : 'glibc'} ${engines.musl || engines.glibc}`;
+      help.push('- Update your OS:');
+      help.push(`    Found ${libcFound}`);
+      help.push(`    Requires ${libcRequires}`);
+    } catch (errEngines) {}
+  }
+  if (isMacOs && /Incompatible library version/.test(messages)) {
+    help.push('- Update Homebrew:');
+    help.push('    brew update && brew upgrade vips');
+  }
+  if (errors.some(err => err.code === 'ERR_DLOPEN_DISABLED')) {
+    help.push('- Run Node.js without using the --no-addons flag');
+  }
+  if (process.versions.pnp) {
+    help.push('- Use a supported yarn linker, either pnpm or node-modules:');
+    help.push('    yarn config set nodeLinker node-modules');
+  }
+  // Link to installation docs
+  if (isWindows && /The specified procedure could not be found/.test(messages)) {
+    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'));
 }

lib/utility.js

@@ -59,11 +59,17 @@ let versions = {
 };
 /* istanbul ignore next */
 if (!libvipsVersion.isGlobal) {
-  try {
-    versions = require(`@img/sharp-${runtimePlatform}/versions`);
-  } catch (_) {
+  if (!libvipsVersion.isWasm) {
     try {
-      versions = require(`@img/sharp-libvips-${runtimePlatform}/versions`);
+      versions = require(`@img/sharp-${runtimePlatform}/versions`);
+    } catch (_) {
+      try {
+        versions = require(`@img/sharp-libvips-${runtimePlatform}/versions`);
+      } catch (_) {}
+    }
+  } else {
+    try {
+      versions = require('@img/sharp-wasm32/versions');
     } catch (_) {}
   }
 }

npm/from-github-release.js

@@ -58,8 +58,8 @@ workspaces.map(async platform => {
   await writeFile(path.join(dir, 'README.md'), `# \`${name}\`\n\n${description}.\n${licensing}`);
   // Copy Apache-2.0 LICENSE
   await copyFile(path.join(__dirname, '..', 'LICENSE'), path.join(dir, 'LICENSE'));
-  // Copy Windows-specific files
-  if (platform.startsWith('win32-')) {
+  // Copy files for packages without an explicit sharp-libvips dependency (Windows, wasm)
+  if (platform.startsWith('win') || platform.startsWith('wasm')) {
     const sharpLibvipsDir = path.join(require(`@img/sharp-libvips-${platform}/lib`), '..');
     // Copy versions.json
     await copyFile(path.join(sharpLibvipsDir, 'versions.json'), path.join(dir, 'versions.json'));

npm/package.json

@@ -11,6 +11,7 @@
     "linux-x64",
     "linuxmusl-arm64",
     "linuxmusl-x64",
+    "wasm32",
     "win32-ia32",
     "win32-x64"
   ]

npm/wasm32/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@img/sharp-wasm32",
+  "version": "0.33.0-alpha.10",
+  "description": "Prebuilt sharp for use with wasm32",
+  "author": "Lovell Fuller <npm@lovell.info>",
+  "homepage": "https://sharp.pixelplumbing.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lovell/sharp.git",
+    "directory": "npm/wasm32"
+  },
+  "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT",
+  "funding": {
+    "url": "https://opencollective.com/libvips"
+  },
+  "preferUnplugged": true,
+  "files": [
+    "lib",
+    "versions.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "exports": {
+    "./sharp.node": "./lib/sharp-wasm32.node.js",
+    "./package": "./package.json",
+    "./versions": "./versions.json"
+  },
+  "engines": {
+    "node": "^18.17.0 || ^20.3.0 || >=21.0.0",
+    "npm": ">=9.6.5",
+    "yarn": ">=3.2.0",
+    "pnpm": ">=7.1.0"
+  },
+  "dependencies": {
+    "@emnapi/runtime": "^0.43.1"
+  },
+  "cpu": [
+    "wasm32"
+  ]
+}

package.json

@@ -156,16 +156,20 @@
     "@img/sharp-linux-x64": "0.33.0-alpha.10",
     "@img/sharp-linuxmusl-arm64": "0.33.0-alpha.10",
     "@img/sharp-linuxmusl-x64": "0.33.0-alpha.10",
+    "@img/sharp-wasm32": "0.33.0-alpha.10",
     "@img/sharp-win32-ia32": "0.33.0-alpha.10",
     "@img/sharp-win32-x64": "0.33.0-alpha.10"
   },
   "devDependencies": {
+    "@emnapi/runtime": "^0.43.1",
     "@img/sharp-libvips-dev": "0.0.3",
+    "@img/sharp-libvips-dev-wasm32": "0.0.3",
     "@img/sharp-libvips-win32-ia32": "0.0.3",
     "@img/sharp-libvips-win32-x64": "0.0.3",
     "@types/node": "*",
-    "async": "^3.2.4",
+    "async": "^3.2.5",
     "cc": "^3.0.1",
+    "emnapi": "^0.43.1",
     "exif-reader": "^2.0.0",
     "extract-zip": "^2.0.1",
     "icc": "^3.0.0",
@@ -203,6 +207,11 @@
       "build/include"
     ]
   },
+  "nyc": {
+    "include": [
+      "lib"
+    ]
+  },
   "tsd": {
     "directory": "test/types/"
   }