feat: add Node.js 24 LTS (Krypton) support (#1340)

Integrated into release/v3.6.7

.github/workflows/ci.yml

@@ -16,6 +16,7 @@ permissions:
 
 env:
   CI_NODE_VERSION: "22.22.2"
+  CI_NODE_24_VERSION: "24"
 
 jobs:
   lint:
@@ -185,6 +186,26 @@ jobs:
       - run: npm run check:node-runtime
       - run: npm run test:unit
 
+  node-24-compat:
+    name: Node 24 Compatibility
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: build
+    env:
+      JWT_SECRET: ci-test-secret-with-sufficient-length-for-validation
+      API_KEY_SECRET: ci-test-api-key-secret-long
+      DISABLE_SQLITE_AUTO_BACKUP: "true"
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_24_VERSION }}
+          cache: npm
+      - run: npm ci
+      - run: npm run check:node-runtime
+      - run: npm run build
+      - run: npm run test:unit
+
   test-coverage:
     name: Coverage
     runs-on: ubuntu-latest
@@ -413,6 +434,7 @@ jobs:
       - build
       - package-artifact
       - test-unit
+      - node-24-compat
       - test-coverage
       - sonarqube
       - coverage-pr-comment

.github/workflows/npm-publish.yml

@@ -38,7 +38,7 @@ permissions:
   packages: write
 
 env:
-  NPM_PUBLISH_NODE_VERSION: "22.22.2"
+  NPM_PUBLISH_NODE_VERSION: "24"
 
 jobs:
   publish:

.node-version

@@ -1 +1 @@
-22
+24

.nvmrc

@@ -1 +1 @@
-22
+24

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:22.22.2-trixie-slim AS builder
+FROM node:24-trixie-slim AS builder
 WORKDIR /app
 
 RUN apt-get update \
@@ -13,7 +13,7 @@ RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm inst
 COPY . ./
 RUN mkdir -p /app/data && npm run build -- --webpack
 
-FROM node:22.22.2-trixie-slim AS runner-base
+FROM node:24-trixie-slim AS runner-base
 WORKDIR /app
 
 LABEL org.opencontainers.image.title="omniroute" \

docker-compose.yml

@@ -101,7 +101,7 @@ services:
       # Adjust paths below to match YOUR host system.
       - ~/.local/bin:/host-local/bin:ro
       # Node global binaries (adjust node version path)
-      # - ~/.nvm/versions/node/v22.16.0/bin:/host-node/bin:ro
+      # - ~/.nvm/versions/node/v24.14.1/bin:/host-node/bin:ro
       # ── Host config mounts (read-write) ──
       - ~/.codex:/host-home/.codex:rw
       - ~/.claude:/host-home/.claude:rw

docs/TROUBLESHOOTING.md

@@ -64,7 +64,7 @@ Common problems and solutions for OmniRoute.
 - Full example:
 
 ```
-dlopen(/Users/<user>/.nvm/versions/node/v24.13.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
+dlopen(/Users/<user>/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)
 ```
 
 **Fix — rebuild for your local environment (no Node.js downgrade required):**
@@ -75,7 +75,7 @@ npm rebuild better-sqlite3
 omniroute
 ```
 
-> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported secure range is now **`>=20.20.2 <21` or `>=22.22.2 <23`** (`engines` field in `package.json`). If you are on Node.js 24, the rebuild may silence this specific startup error but other issues can still occur — moving to a patched Node.js 22 LTS release remains the recommended path.
+> **Note:** This recompiles the native binding against your local Node.js version and CPU architecture, resolving the binary mismatch. The officially supported range is **`>=20.20.2 <21`, `>=22.22.2 <23`, or `>=24.0.0 <25`** (`engines` field in `package.json`). Node.js 24.x LTS (Krypton) is fully supported with `better-sqlite3` v12.x.
 
 ---
 

package.json

@@ -34,7 +34,7 @@
     "open-sse"
   ],
   "engines": {
-    "node": ">=20.20.2 <21 || >=22.22.2 <23"
+    "node": ">=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <25"
   },
   "keywords": [
     "ai",

src/shared/utils/nodeRuntimeSupport.ts

@@ -10,11 +10,13 @@
 export const SECURE_NODE_LINES = Object.freeze([
   Object.freeze({ major: 20, minor: 20, patch: 2 }),
   Object.freeze({ major: 22, minor: 22, patch: 2 }),
+  Object.freeze({ major: 24, minor: 0, patch: 0 }),
 ]);
 
-export const RECOMMENDED_NODE_VERSION = "22.22.2";
-export const SUPPORTED_NODE_RANGE = ">=20.20.2 <21 || >=22.22.2 <23";
-export const SUPPORTED_NODE_DISPLAY = "Node.js 20.20.2+ (20.x LTS) or 22.22.2+ (22.x LTS)";
+export const RECOMMENDED_NODE_VERSION = "24.14.1";
+export const SUPPORTED_NODE_RANGE = ">=20.20.2 <21 || >=22.22.2 <23 || >=24.0.0 <25";
+export const SUPPORTED_NODE_DISPLAY =
+  "Node.js 20.20.2+ (20.x LTS), 22.22.2+ (22.x LTS), or 24.x (24.x LTS)";
 
 export interface NodeVersionInfo {
   major: number;
@@ -78,8 +80,8 @@ export function getNodeRuntimeSupport(version: string = process.versions.node):
     reason = "supported";
   } else if (secureFloor) {
     reason = "below-security-floor";
-  } else if (parsed.major >= 24) {
-    reason = "native-addon-incompatible";
+  } else if (parsed.major >= 25) {
+    reason = "unreleased-major";
   }
 
   return {
@@ -101,8 +103,8 @@ export function getNodeRuntimeWarning(version: string = process.versions.node):
     return `Node.js ${support.nodeVersion} is below the patched minimum ${support.minimumSecureVersion} for this LTS line.`;
   }
 
-  if (support.reason === "native-addon-incompatible") {
-    return `Node.js ${support.nodeVersion} is outside the supported LTS lines and may fail at runtime because better-sqlite3 does not support Node.js 24+ here.`;
+  if (support.reason === "unreleased-major") {
+    return `Node.js ${support.nodeVersion} is outside the supported LTS lines. OmniRoute currently supports Node.js 20.x, 22.x, and 24.x.`;
   }
 
   return `Node.js ${support.nodeVersion} is outside OmniRoute's approved secure runtime policy.`;