spotify · canbakiskan · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025 · Oct 19, 2025
diff --git a/.github/workflows/all.yml b/.github/workflows/all.yml
diff --git a/.github/workflows/npm_publish.yml b/.github/workflows/npm_publish.yml
@@ -0,0 +1,69 @@
+name: Publish voyager-node to NPM
+on:
+  workflow_dispatch:
+jobs:
+  build:
+    strategy:
+      matrix:
+        include:
+          - os: macos-latest
+            arch: arm64
+            node-version: 20.x
+          - os: ubuntu-latest
+            arch: x64
+            node-version: 20.x
+          - os: windows-latest
+            arch: x64
+            node-version: 20.x
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v5
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install dependencies
+        working-directory: ./nodejs
+        run: npm install
+      - name: Run prebuildify for ${{ matrix.os }} - ${{ matrix.arch }}
+        working-directory: ./nodejs
+        run: npm run prebuildify
+        env:
+          TARGET_ARCH: ${{ matrix.arch }}
+      - name: Upload prebuild artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: prebuilds-${{ matrix.os }}-${{ matrix.arch }}
+          path: nodejs/prebuilds
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v6
+        with:
+          node-version: 20.x
+          registry-url: "https://registry.npmjs.org"
+      - name: Install dependencies
+        working-directory: ./nodejs
+        run: npm install
+      - name: Download all prebuild artifacts
+        uses: actions/download-artifact@v5
+        with:
+          path: nodejs/prebuilds-temp
+          pattern: prebuilds-*
+          merge-multiple: true
+      - name: Move prebuilds to correct location
+        run: |
+          mkdir -p nodejs/prebuilds
+          mv nodejs/prebuilds-temp/* nodejs/prebuilds/
+          rm -rf nodejs/prebuilds-temp
+      - name: Build TypeScript
+        working-directory: ./nodejs
+        run: npm run build-ts
+      - name: Publish to npm
+        working-directory: ./nodejs
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,90 +1,44 @@
-![The word Voyager_in blue, with a multicoloured graphic illustrating an orbit to its left.](https://github.com/spotify/voyager/assets/213293/c99cd0e8-cd38-486f-bb61-15f74028ba52)
+# voyager-node: Node.js Bindings for Spotify's Voyager ANN Library
 
-[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/spotify/voyager/blob/master/LICENSE)
-[![Documentation](https://img.shields.io/badge/Documentation-on%20github.io-brightgreen)](https://spotify.github.io/voyager)
-[![Supported Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Windows%20%7C%20Linux-green)](https://pypi.org/project/voyager)
-[![Apple Silicon support for macOS and Linux (Docker)](https://img.shields.io/badge/Apple%20Silicon-macOS%20and%20Linux-brightgreen)](https://pypi.org/project/voyager)
-[![Test Badge](https://github.com/spotify/voyager/actions/workflows/all.yml/badge.svg)](https://github.com/spotify/voyager/actions/workflows/all.yml)
-<!-- [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/voyager)](https://pypi.org/project/voyager) -->
-<!-- [![PyPI - Wheel](https://img.shields.io/pypi/wheel/voyager)](https://pypi.org/project/voyager) -->
-<!-- [![PyPI - Downloads](https://img.shields.io/pypi/dm/voyager)](https://pypistats.org/packages/voyager) -->
-<!-- [![GitHub Repo stars](https://img.shields.io/github/stars/spotify/voyager?style=social)](https://github.com/spotify/voyager/stargazers) -->
+**Disclaimer:** This project provides Node.js bindings for [Spotify's Voyager](https://github.com/spotify/voyager) approximate nearest neighbor (ANN) search library. It is **not** the official Voyager project, and I am **not affiliated** with Spotify or the Voyager team. The source code is a fork of the original Voyager library, adapted to provide Node.js integration.
 
-**_Voyager_** is a library for performing fast approximate nearest-neighbor searches on an in-memory collection of vectors.
+## About
 
-Voyager features bindings to both Python and Java, with feature parity and index compatibility between both languages. It uses the HNSW algorithm, based on [the open-source `hnswlib` package](https://github.com/nmslib/hnswlib), with numerous features added for convenience and speed. Voyager is used extensively in production at Spotify, and is queried hundreds of millions of times per day to power numerous user-facing features.
+This repository enables Node.js developers to leverage the high-performance ANN search capabilities of Voyager. All credit for the original algorithm and C++ implementation goes to the Spotify Voyager team.
 
-Think of Voyager like [Sparkey](https://github.com/spotify/sparkey), but for vector/embedding data; or like [Annoy](https://github.com/spotify/annoy), but with [much higher recall](http://ann-benchmarks.com/). It got its name because it searches through (embedding) space(s), much like [the Voyager interstellar probes](https://en.wikipedia.org/wiki/Voyager_program) launched by NASA in 1977.
+## License
 
-[![Python Documentation](https://img.shields.io/badge/Python%20Documentation-on%20github.io-brightgreen)](https://spotify.github.io/voyager/python)
-[![Java Documentation](https://img.shields.io/badge/Java%20Documentation-on%20github.io-brightgreen)](https://spotify.github.io/voyager/java)
+This project is distributed under the same license as the original Voyager project. Please refer to the LICENSE file for details.
 
-### Installation
+## Acknowledgements
 
-#### Python
+- [Spotify Voyager](https://github.com/spotify/voyager)
+- The Spotify engineering team for their work on the original library
 
-```shell
-pip install voyager
-```
-
-#### Java
+---
 
-Add the following artifact to your `pom.xml`:
-```xml
-<dependency>
-  <groupId>com.spotify</groupId>
-  <artifactId>voyager</artifactId>
-  <version>2.1.0</version>
-</dependency>
-```
-You can find the latest version on [Voyager's Releases page](https://github.com/spotify/voyager/releases).
+## Installation
 
-#### Scala
+Install via npm:
 
-Add the following artifact to your `build.sbt`:
-```sbt
-"com.spotify" % "voyager" % "2.1.0"
+```sh
+npm install voyager-node
 ```
-You can find the latest version on [Voyager's Releases page](https://github.com/spotify/voyager/releases).
-
-
-### Compatibility
 
-| OS        | Language | Version | x86_64 (Intel) | arm64 (ARM) |
-|-----------|----------|---------|---------| --------|
-| Linux     | Python   | 3.7     | ✅       | ✅       |
-| Linux     | Python   | 3.8     | ✅       | ✅       |
-| Linux     | Python   | 3.9     | ✅       | ✅       |
-| Linux     | Python   | 3.10    | ✅       | ✅       |
-| Linux     | Python   | 3.11    | ✅       | ✅       |
-| Linux     | Python   | 3.12    | ✅       | ✅       |
-| Linux     | Python   | 3.13    | ✅       | ✅       |
-| Linux     | Java     | 8-16+   | ✅       | ✅      |
-| macOS     | Python   | 3.7     | ✅       | ✅       |
-| macOS     | Python   | 3.8     | ✅       | ✅       |
-| macOS     | Python   | 3.9     | ✅       | ✅       |
-| macOS     | Python   | 3.10    | ✅       | ✅       |
-| macOS     | Python   | 3.11    | ✅       | ✅       |
-| macOS     | Python   | 3.12    | ✅       | ✅       |
-| macOS     | Python   | 3.13    | ✅       | ✅       |
-| macOS     | Java     | 8-16+   | ✅       | ✅       |
-| Windows   | Python   | 3.7     | ✅       | ❌       |
-| Windows   | Python   | 3.8     | ✅       | ❌       |
-| Windows   | Python   | 3.9     | ✅       | ❌       |
-| Windows   | Python   | 3.10    | ✅       | ❌       |
-| Windows   | Python   | 3.11    | ✅       | ❌       |
-| Windows   | Python   | 3.12    | ✅       | ❌       |
-| Windows   | Python   | 3.13    | ✅       | ❌       |
-| Windows   | Java     | 8-16+   | ✅       | ❌       |
-
-
-## Contributing
-
-Contributions to `voyager` are welcomed!
-See [CONTRIBUTING.md](https://github.com/spotify/voyager/blob/master/CONTRIBUTING.md) for details.
+## Usage
 
+```js
+// ES module
+import voyager from "voyager-node";
+index = Index.loadIndex(filepath);
+// ... use voyager-node API ...
+```
 
-### License
-Voyager is copyright 2022-2024 Spotify AB.
+or
 
-Voyager is licensed under the [Apache 2 License]([https://www.gnu.org/licenses/gpl-3.0.en.html](https://www.apache.org/licenses/LICENSE-2.0)).
+```js
+// CommonJS
+const voyager = require("voyager-node");
+index = Index.loadIndex(filepath);
+// ... use voyager-node API ...
+```
diff --git a/nodejs/.gitignore b/nodejs/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+build/
+prebuilds/
+voyager_src/
diff --git a/nodejs/README.md b/nodejs/README.md
@@ -0,0 +1,39 @@
+# voyager-node
+
+[![npm version](https://img.shields.io/npm/v/voyager-node.svg)](https://www.npmjs.com/package/voyager-node)
+
+Node.js bindings for [Spotify's Voyager](https://github.com/spotify/voyager) approximate nearest neighbor (ANN) search library.
+
+---
+
+**Disclaimer:** This package is not affiliated with Spotify or the Voyager team. It is a community-maintained fork providing Node.js integration for Voyager ANN. All credit for the original algorithm and C++ implementation goes to the Spotify Voyager team.
+
+## Installation
+
+```sh
+npm install voyager-node
+```
+
+## Usage
+
+```js
+// ES module
+import voyager from "voyager-node";
+index = Index.loadIndex(filepath);
+// ... use voyager-node API ...
+```
+
+or
+
+```js
+// CommonJS
+const voyager = require("voyager-node");
+index = Index.loadIndex(filepath);
+// ... use voyager-node API ...
+```
+
+See the main repository for detailed documentation and examples.
+
+## License
+
+Distributed under the same license as the original Voyager project. See LICENSE for details.
diff --git a/nodejs/binding.gyp b/nodejs/binding.gyp
@@ -0,0 +1,69 @@
+{
+  "targets": [
+    {
+      "target_name": "voyager-node",
+      "cflags!": [
+        "-fno-exceptions"
+      ],
+      "cflags_cc!": [
+        "-fno-exceptions"
+      ],
+      "cflags_cc": [
+        "-std=c++17",
+        "-O3"
+      ],
+      "sources": [
+        "src/voyager-node.cc"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "voyager_src",
+        "../cpp/src"
+      ],
+      "defines": [
+        "NAPI_CPP_EXCEPTIONS"
+      ],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+        "CLANG_CXX_LANGUAGE_STANDARD": "c++17",
+        "CLANG_CXX_LIBRARY": "libc++",
+        "MACOSX_DEPLOYMENT_TARGET": "10.15",
+        "OTHER_CFLAGS": [
+          "-O3"
+        ]
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "ExceptionHandling": 1,
+          "AdditionalOptions": [
+            "/std:c++17"
+          ]
+        }
+      },
+      "conditions": [
+        [
+          "OS=='linux'",
+          {
+            "cflags_cc": [
+              "-std=c++17",
+              "-O3",
+              "-pthread"
+            ],
+            "ldflags": [
+              "-pthread"
+            ]
+          }
+        ],
+        [
+          "OS=='mac'",
+          {
+            "cflags_cc": [
+              "-std=c++17",
+              "-O3"
+            ]
+          }
+        ]
+      ]
+    }
+  ]
+}