Feature request: Support for Debian base (e.g. node:24-slim) in Node.js platform/docker builds

[victor314159]

Is your feature request related to a problem? Please describe.
Currently, the Node.js platform binaries are only built and supported for Ubuntu 24.04 images. I would like to use MapLibre Native from a Docker image based on Debian (for example, node:24-slim), but Debian is not officially supported and there is no guidance or binary distribution for it.

Describe the solution you'd like

• Add support for building and distributing Node.js binaries for Debian (slim) base images, especially for usage in node:<version>-slim
• Update CI/workflows to include Debian builds alongside Ubuntu
• Provide Docker build instructions (and ideally prebuilt binaries) for Debian, similar to Ubuntu

Describe alternatives you've considered

• Tried using Ubuntu binaries—risk of missing dependencies or incompatibilities
• Building from source inside a Debian image (not straightforward for all users)
• Sticking with Ubuntu images as a workaround (less ideal for some environments)

Additional context
If there are technical challenges, guidance on what would be needed to unblock Debian support would also be very helpful. This would broaden compatibility for developers using official Node docker images (which default to Debian-based).

[victor314159]

I was able to build from source using this dockerfile:

# Multi-stage build: Build MapLibre Native from source
FROM node:24-slim AS builder

# Install build dependencies
RUN apt-get update && apt-get install -y \
    build-essential \
    clang \
    cmake \
    ccache \
    ninja-build \
    pkg-config \
    git \
    libcurl4-openssl-dev \
    libglfw3-dev \
    libuv1-dev \
    libpng-dev \
    libicu-dev \
    libjpeg62-turbo-dev \
    libwebp-dev \
    xvfb \
    libgl1-mesa-dev \
    libegl1-mesa-dev \
    libgles2-mesa-dev \
    libx11-dev \
    libxext-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /build

# Clone MapLibre Native repository
RUN git clone --recurse-submodules --depth 1 --branch main https://github.com/maplibre/maplibre-native.git

WORKDIR /build/maplibre-native

# Configure and build the Node.js bindings
RUN cmake . -B build -G Ninja \
    -DMLN_WITH_NODE=ON \
    -DMLN_WITH_OPENGL=ON \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
    -DMLN_WITH_WERROR=OFF

RUN cmake --build build -j $(nproc)

# Runtime stage
FROM node:24-slim

# Install runtime dependencies only
RUN apt-get update && apt-get install -y \
    libcurl4 \
    libuv1 \
    libpng16-16 \
    libicu72 \
    libjpeg62-turbo \
    libwebp7 \
    libglx0 \
    libgl1 \
    libopengl0 \
    libegl1 \
    libgles2 \
    libx11-6 \
    libxext6 \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install other npm dependencies (excluding @maplibre/maplibre-gl-native)
RUN npm install --ignore-scripts || true

# Copy the built MapLibre Native module from builder
RUN mkdir -p node_modules/@maplibre/maplibre-gl-native
COPY --from=builder /build/maplibre-native/platform/node/index.js node_modules/@maplibre/maplibre-gl-native/
COPY --from=builder /build/maplibre-native/platform/node/index.d.ts node_modules/@maplibre/maplibre-gl-native/
COPY --from=builder /build/maplibre-native/platform/node/package.json node_modules/@maplibre/maplibre-gl-native/
COPY --from=builder /build/maplibre-native/platform/node/README.md node_modules/@maplibre/maplibre-gl-native/

# Copy the compiled .node files to the lib directory with correct naming
# Node.js v24 uses ABI version 137
RUN mkdir -p node_modules/@maplibre/maplibre-gl-native/lib/node-v137
COPY --from=builder /build/maplibre-native/build/platform/node/mbgl-node.abi-137.node \
    node_modules/@maplibre/maplibre-gl-native/lib/node-v137/mbgl.node

# Copy application code
COPY . .

# Run the test
CMD ["npm", "start"]

However I'm not familiar enough with the CI/CD to create a PR. It would be really cool if this scenario would be supported.

[louwers]

One solution may be to use an amalgamation where dependencies are included, but I'm not sure what kind of problems that may cause.

cc @acalcutt

[acalcutt]

Since you already have the lib files building in the docker, you mostly just need to package what is in /build/maplibre-native/platform/node/lib/ and copy that into your node_modules/@maplibre/maplibre-gl-native/lib/ folder on whatever application needs to use it.

If you want to package up the lib files in a way the node-pre-gyp installer can use, you have to package those lib files into platform-specific tgz files. Typically, our build process does this with https://github.com/maplibre/maplibre-native/blob/main/platform/node/scripts/publish.sh, which runs ./node_modules/.bin/node-pre-gyp package --target="${TARGET}" $@ to make the tgz files. The tgz files get uploaded to a GitHub release with ./node_modules/.bin/node-pre-gyp-github publish in that script.

The main issue with providing additional binaries is that 'node-pre-gyp' packager does not make a distinction between versions of Linux, so the tgz file generated applies to all Linux distributions. The only option for using an alternate binary is really this node-pre-gyp option mentioned here: https://github.com/mapbox/node-pre-gyp?tab=readme-ov-file#download-binary-files-from-a-mirror, which I tried once but would have to figure out how to use again. With that option, you could point to your own binary on install.

---

Last time I looked into making our node package buildable, I made this package which uses maplibre-native as a sub-package so it has the files needed to build the binaries:
https://github.com/acalcutt/maplibre-native-with-source

In that, I basically used a build script:
https://github.com/acalcutt/maplibre-native-with-source/blob/main/scripts/build-maplibre.js

Then a script to package the files—I had to play some tricks with npm ignore:
https://github.com/acalcutt/maplibre-native-with-source/blob/main/scripts/prepack.js

Something like this could be made as a standalone package, I think. The source code needed is quite large, so I don't think it would be good as the standard package.

---

I also spent some time on this PR for replacing node-pre-gyp with prebuild, but it took a bit more scripting that I liked it did seems to work
#3819 . pebuild has some better options for alternative biaries than node-pre-gyp