Netlify Build Uses Stale pnpm Lock and Misses Tailwind Native Binding

Problem

The PR deploy was mergeable locally and npm run codex:check passed, but Netlify deploy previews still failed while building the Jekyll site. The failure blocked deploy preview checks even after merge conflicts were resolved.

Symptoms

• GitHub initially reported the PR as conflicted (DIRTY/CONFLICTING), and Netlify deploys failed.
• After rebasing and resolving conflicts, the PR became mergeable but Netlify still failed.
• Netlify’s build log showed jekyll-postcss failing while converting assets/css/main.css.
• The underlying Node error was Cannot find native binding, with a missing @tailwindcss/oxide-linux-x64-gnu module.
• The log showed Netlify using Node 18.20.8 and installing packages with pnpm from a stale pnpm-lock.yaml.

What Didn’t Work

• Resolving the Git conflicts alone fixed GitHub mergeability but did not fix the deploy.
• Adding Linux Ruby platforms to Gemfile.lock was necessary for clean Linux bundle installs, but it did not address the Tailwind native binding failure.
• Aligning netlify.toml to run npm run build was useful because it matched the verified local build path, but Netlify still selected pnpm before running that command.
• Local macOS builds could not reproduce the failure because npm install had installed the Darwin native packages correctly and local Node was already new enough.

Solution

Make Netlify install JavaScript dependencies through the same package manager and lockfile that the repo actually maintains.

Remove the stale pnpm lockfile:

- pnpm-lock.yaml

Declare npm as the package manager and pin a Node version compatible with the current dependency tree:

{
  "engines": {
    "node": ">=24.11.0",
    "npm": ">=11.0.0"
  },
  "packageManager": "npm@11.6.2"
}

Pin Netlify’s Node runtime in netlify.toml:

[build]
  publish = "_site"
  command = "npm run build"

[build.environment]
  NODE_VERSION = "24.13.0"

Keep package-lock.json as the canonical JavaScript lockfile. It includes the Linux Tailwind native package Netlify needs:

node_modules/@tailwindcss/oxide-linux-x64-gnu

Also include Linux platforms in Gemfile.lock so Netlify can install platform-specific Ruby gems without falling back to local-only Darwin entries:

PLATFORMS
  aarch64-linux
  x86_64-linux

Why This Works

Netlify chooses its JavaScript installer from the lockfiles it finds. A stale pnpm-lock.yaml caused Netlify to install with pnpm even though the updated dependency graph was represented in package-lock.json.

Tailwind 4 loads a platform-specific native package through @tailwindcss/oxide. On Linux, that package is @tailwindcss/oxide-linux-x64-gnu. Because the stale pnpm lock described an older Tailwind dependency graph, the Linux native package was not installed, and PostCSS crashed when Jekyll processed assets/css/main.css.

Removing the stale lockfile makes Netlify use npm and package-lock.json, where the Linux optional package is present. Pinning Node prevents Netlify from selecting an older default runtime that is incompatible with newer CSS tooling such as cssnano@8.

Prevention

• Keep exactly one JavaScript lockfile unless the repo intentionally supports multiple package managers.
• After dependency migrations, remove stale lockfiles from other package managers before opening the PR.
• Pin deploy runtimes when dependency upgrades introduce stricter engine requirements.
• Check generated lockfiles for platform-specific optional packages when a deploy-only failure mentions missing native bindings.
• Reproduce the deploy path with the configured build command, but trust the hosted deploy log for package-manager selection and runtime differences.

Related Issues

• PR: alexbaldwin/hackdesign.org#29
• Deploy preview after fix: deploy-preview-29–hackdesign-jekyll.netlify.app