Node.js v24 Compatibility Issue with TanStack Router Generator in Deno Runtime

[rickylabs]

Which project does this relate to?

Start and probably Router

Describe the bug

Description

When running TanStack Start with virtual routes in Deno runtime, the router generator fails with a misleading error message about Node.js version compatibility.

Error Message

Error: This version of Node.js (v24.2.0) does not support module.register(). Please upgrade to Node v18.19 or v20.6 and above.
    at file:///C:/Dev/repos/microfrontend/node_modules/.deno/@tanstack+router-generator@1.132.31/node_modules/@tanstack/router-generator/dist/esm/generator.js:141:19

Root Cause

• Node.js v24.2.0 does support module.register() (added in Node 18.19/20.6)
• Deno's Node.js compatibility layer doesn't implement module.register() ?
• TanStack Router Generator checks version numbers but doesn't detect Deno runtime ?
• The error message incorrectly suggests upgrading Node.js when the actual issue is Deno incompatibility

Dependencies

{
    "@tanstack/nitro-v2-vite-plugin": "npm:@tanstack/nitro-v2-vite-plugin@^1.132.31",
    "@tanstack/react-devtools": "npm:@tanstack/react-devtools@^0.7.0",
    "@tanstack/react-form": "npm:@tanstack/react-form@^1.0.0",
    "@tanstack/react-query": "npm:@tanstack/react-query@^5.66.5",
    "@tanstack/react-query-devtools": "npm:@tanstack/react-query-devtools@^5.84.2",
    "@tanstack/react-router": "npm:@tanstack/react-router@^1.132.0",
    "@tanstack/react-router-devtools": "npm:@tanstack/react-router-devtools@^1.132.0",
    "@tanstack/react-router-ssr-query": "npm:@tanstack/react-router-ssr-query@^1.131.7",
    "@tanstack/react-start": "npm:@tanstack/react-start@^1.132.0",
    "@tanstack/router-plugin": "npm:@tanstack/router-plugin@^1.132.0",
    "@tanstack/start-plugin-core": "npm:@tanstack/start-plugin-core@^1.132.0",
    "@tanstack/virtual-file-routes": "npm:@tanstack/virtual-file-routes@^1.132.0",
}

Code Sample

import {
    defineVirtualSubtreeConfig,
    index,
    physical,
    route,
} from '@tanstack/virtual-file-routes'

export default defineVirtualSubtreeConfig(async () => [
    index('home.tsx')
])

Your Example Website or App

https://github.com/TanStack/router/tree/main/examples/react/basic-virtual-inside-file-based

Steps to Reproduce the Bug or Issue

1. Clone the basic virtual route example:

git clone https://github.com/TanStack/router.git
cd router/examples/react/basic-virtual-inside-file-based

2. Convert to Deno project by creating a deno.jsonc file:

{
  "name": "tanstack-router-example",
  "imports": {
    "@deno/vite-plugin": "npm:@deno/vite-plugin@^1.0.5",
    "@tailwindcss/vite": "npm:@tailwindcss/vite@^4.0.6",
    "@tanstack/nitro-v2-vite-plugin": "npm:@tanstack/nitro-v2-vite-plugin@^1.132.31",
    "@tanstack/react-router": "npm:@tanstack/react-router@^1.132.0",
    "@tanstack/react-router-devtools": "npm:@tanstack/react-router-devtools@^1.132.0",
    "@tanstack/react-start": "npm:@tanstack/react-start@^1.132.0",
    "@tanstack/router-plugin": "npm:@tanstack/router-plugin@^1.132.0",
    "@tanstack/start-plugin-core": "npm:@tanstack/start-plugin-core@^1.132.0",
    "@tanstack/virtual-file-routes": "npm:@tanstack/virtual-file-routes@^1.132.0",
    "react": "npm:react@^19.2.0",
    "react-dom": "npm:react-dom@^19.2.0",
    "tailwindcss": "npm:tailwindcss@^4.0.6",
    "vite-tsconfig-paths": "npm:vite-tsconfig-paths@^5.1.4",
    "@types/react": "npm:@types/react@^19.0.8",
    "@types/react-dom": "npm:@types/react-dom@^19.0.3",
    "@vitejs/plugin-react": "npm:@vitejs/plugin-react@^5.0.4",
    "typescript": "npm:typescript@^5.7.2",
    "vite": "npm:vite@^7.1.7"
  },
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "react",
    "lib": ["deno.window", "dom", "dom.iterable"]
  },
  "tasks": {
    "dev": "deno run --allow-all --watch npm:vite@^7.1.7 dev --port 3000"
  }
}

3. Update Vite configuration:

import { defineConfig } from 'vite'
import { tanstackStart } from '@tanstack/react-start/plugin/vite'
import viteReact from '@vitejs/plugin-react'
import viteTsConfigPaths from 'vite-tsconfig-paths'
import tailwindcss from '@tailwindcss/vite'
import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin'
import deno from "@deno/vite-plugin";

const config = defineConfig({
  plugins: [
    nitroV2Plugin({
      preset: 'deno_server'
    }),
    viteTsConfigPaths({
      projects: ['./tsconfig.json'],
    }),
    tailwindcss(),
    tanstackStart({
      target: "deno_server",
      router: {
        verboseFileRoutes: false,
        autoCodeSplitting: true
      }
    }),
    viteReact(),
    deno(),
  ],
})

export default config

4. Run the development server using Deno:

deno task dev

Expected behavior

Expected Behavior:

• The router generator should detect Deno runtime and provide a clear error message indicating Deno is not supported
• Alternatively, provide a fallback that works without module.register()
• Documentation should clearly state Deno compatibility status

Actual Behavior:

• The generator fails with a misleading error message suggesting to "upgrade to Node v18.19 or v20.6 and above" when the reported version is already v24.2.0
• No indication that the issue is related to Deno's Node.js compatibility layer limitations

Suggested Fix

No response

Screenshots or Videos

No response

Platform

• Runtime: Deno (using Node.js compatibility layer)
• Node.js version (emulated): v24.2.0
• Vite: v7.1.8
• OS: Windows

Additional context

• module.register() is available in actual Node.js v24.2.0
• This is (maybe) specifically a Deno Node.js compatibility layer limitation
• Not tested whether the same error occurs in standard Node.js v24.x projects (though unlikely given the error message logic)

[schiller-manuel]

seems to be caused by tsx not supporting deno

privatenumber/tsx#682

maybe worth exploring jiti? https://github.com/unjs/jiti