Because compiled code differs by operating system and CPU. The sharp image library ships ready made sharp and libvips binaries, and your package manager picks the right one for the machine at install time. That works only if optional dependencies are installed, and it affects what your lockfile and scanner see.
What the sharp docs say
Sharp's installation page opens with a caution to make sure your package manager is configured to install optional dependencies. It lists the platforms that have prebuilt binaries, such as macOS on x64 and ARM64 and several Linux variants. It explains that at install time, package managers automatically select prebuilt binaries for the current OS platform and CPU architecture where available.
It also warns that some package managers support several platforms in one lockfile, and that npm lockfiles shared across platforms need care. The page links to cross platform guidance on how to choose a package manager for that case.
Why a build engineer should care
Image optimization is common in front-end builds, in frameworks and in static site generators. A package like this is a native binary dependency. That brings three questions:
| Question | Why it matters |
|---|---|
| Does CI install optional dependencies | If not, builds fail or fall back unexpectedly |
| Which platform package lands in the lockfile | A lockfile made on one OS may lack another OS entry |
| Does the scanner see platform packages | A scanner that skips optional entries misses real code that runs in the build |
Optional dependencies are real code on disk. They are only optional in the sense that npm continues if one fails to install. See what happens when an optional dependency fails to install for the install behavior and overrides, aliases and optional dependencies in scan results for how scanners treat them.
Common mistakes
- Using an omit optional flag in CI to speed up installs, then wondering why the image step fails. The sharp docs call out optional dependencies as required for its binaries.
- Building a Docker image on a Mac laptop and a Linux server with the same lockfile, so the platform package for one is missing. Install inside the target environment, as in npm ci or npm install in a Dockerfile.
- Assuming a clean scan means the binary was checked. The binary is inside a package, and your scanner should list that package and version.
A short procedure
- Run npm ls on the image package and find which platform package your machine installed.
- Confirm CI installs optional dependencies, and that the platform package for the CI runner appears.
- Commit the lockfile and install with npm ci, so the exact version is what runs.
- Make sure your SBOM includes the platform packages, or at least the parent with its version, and that your scanner reads the lockfile rather than only package.json.
- Review the maintainer and release history of native packages more carefully than pure JavaScript ones, because a binary is harder to read than source.
- Do not run the image step in a job that holds deploy secrets.
Why binaries raise the bar
Source can be diffed. A compiled binary cannot be reviewed line by line, so trust comes from where it was built, who published it and whether the version matches the source release. Registry provenance and signature checks help where they exist, but they tell you where a package came from, not that its contents are safe.
Safeguard's SBOM and dependency scanning list the packages in your lockfile, including platform specific ones, and its free scan at gold.safeguard.sh/scan is a fast way to see them.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how packages from the lockfile are listed with their versions.
Quick check
Are optional dependencies safe to skip?
For sharp, no. Its documentation says to make sure optional dependencies are installed, because the platform binaries arrive that way.
Does a lockfile from my laptop work on a Linux build server?
Not always. Sharp's docs warn that lockfiles shared across platforms need care. Test the install in the target environment.
Sources
Last reviewed: 19 October 2026.
