Skip to content
Source
Sign inSign up
TanStack/router

fix: use h3 alias only in nitro-v2-plugin #5370

Mergedschiller-manuel(GitHub profile, opens in a new tab)merged 2 commits intomain fromrefs/pull/5370/headmerged by schiller-manuel(GitHub profile, opens in a new tab)

avoid issues with nitro v3

see https://github.com/nitrojs/nitro/issues/3613#issuecomment-3368990799

Summary by CodeRabbit

  • Bug Fixes

    • Improved build compatibility by ensuring consistent resolution of h3 imports in the Nitro Vite plugin.
  • Chores

    • Added an alias to support h3 v1 for internal tooling.
    • Upgraded server runtime dependency to h3 2.0.0-beta.5.
    • Updated Vite configuration to disable CommonJS output.
    1. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: start-server-core

    2. github-actions[bot](GitHub profile, opens in a new tab) added labelspackage: nitro-v2-vite-plugin

    3. Walkthrough

      Adds an h3-v1 alias to Nitro V2 Vite plugin deps, injects a Rollup resolveId hook that maps import 'h3' to the resolved h3-v1 for specific importers, sets cjs: false in the plugin Vite config, and updates start-server-core to import h3@2.0.0-beta.5.

      Changes

      Cohort / File(s)Summary
      Dependency aliasing & version updates
      packages/nitro-v2-vite-plugin/package.json, packages/start-server-core/package.json
      Adds h3-v1 alias (npm:h3@^1.15.4) to nitro plugin deps; replaces h3-v2 (npm:h3@2.0.0-beta.4) with h3@2.0.0-beta.5 in start-server-core.
      Vite plugin: resolver logic
      packages/nitro-v2-vite-plugin/src/index.ts
      Adds Node ESM createRequire, resolves h3-v1 at runtime, and injects a Rollup resolveId hook to map imports of 'h3' to the resolved h3-v1 path for nitropack-related or virtual entry importers.
      Build configuration
      packages/nitro-v2-vite-plugin/vite.config.ts
      Sets cjs: false in the tanstackViteConfig options passed to Vite config.
      Source import alignment
      packages/start-server-core/src/request-response.ts
      Replaces imports from h3-v2 to h3 without API signature changes.

      Sequence Diagram(s)

      sequenceDiagram
        participant Dev as Developer
        participant Vite as Vite/Rollup
        participant Plugin as nitroV2Plugin (resolveId)
        participant Node as Node (createRequire / require.resolve)
        participant h3v1 as h3-v1 (npm:h3@^1.15.4)
      
        Dev->>Vite: Start build for Nitro bundle
        Vite->>Plugin: resolveId('h3', importer)
        alt importer is nitropack-related or virtual entry
          Plugin->>Node: require.resolve('h3-v1')
          Node-->>Plugin: resolved path to h3-v1
          Plugin-->>Vite: return resolved h3-v1 path
          Vite->>h3v1: load resolved module
        else other importers
          Plugin-->>Vite: no mapping (defer)
        end

      Estimated code review effort

      🎯 3 (Moderate) | ⏱️ ~20 minutes

      • TanStack/router#5281 — Modifies h3 import/alias usage and overlaps with this PR's changes to h3 aliasing and import sources.

      Poem

      A rabbit hops through module trees, Swapping paths with graceful ease. "h3" guided gently to its den, Vite and server stitched again. Soft paws press play — build runs, amen. 🐇✨

      Pre-merge checks and finishing touches

      ✅ Passed checks (3 passed)
      Check nameStatusExplanation
      Description Check✅ PassedCheck skipped - CodeRabbit’s high-level summary is enabled.
      Title Check✅ PassedThe title clearly indicates that the pull request fixes the usage of the h3 alias specifically in the nitro-v2 plugin, which aligns with the primary changes. It follows conventional commit style with a “fix:” prefix and is concise without extraneous details. This makes it easy for teammates scanning the history to understand the core purpose of the change.
      Docstring Coverage✅ PassedNo functions found in the changes. Docstring coverage check skipped.
      ✨ Finishing touches
      • 📝 Generate docstrings
        🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Post copyable unit tests in a comment
      • Commit unit tests in branch `h3-alias`

      📜 Recent review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between 3ab08790162290f0f07bd23a033a289288ed098e and edd4f1302cb45b4371737f9f74c37dae55506627.

      📒 Files selected for processing (2)
      • packages/nitro-v2-vite-plugin/package.json (1 hunks)
      • packages/nitro-v2-vite-plugin/src/index.ts (4 hunks)
      🚧 Files skipped from review as they are similar to previous changes (1)
      • packages/nitro-v2-vite-plugin/package.json
      🧰 Additional context used
      📓 Path-based instructions (1)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/nitro-v2-vite-plugin/src/index.ts
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Preview
      • GitHub Check: Test
      🔇 Additional comments (1)
      packages/nitro-v2-vite-plugin/src/index.ts (1)

      117-131: Scoped aliasing looks solid

      Limiting the h3→h3-v1 remap to Nitro’s own modules neatly sidesteps the v3 break while letting the host app keep its chosen h3 version. 👍


      Comment `@coderabbitai help` to get the list of available commands and usage tips.
    4. View your CI Pipeline Execution ↗ for commit edd4f1302cb45b4371737f9f74c37dae55506627

      CommandStatusDurationResult
      nx affected --targets=test:eslint,test:unit,tes...✅ Succeeded1m 16sView ↗
      nx run-many --target=build --exclude=examples/*...✅ Succeeded4sView ↗

      ☁️ Nx Cloud last updated this comment at 2025-10-05 13:26:20 UTC

    5. More templates

      @tanstack/arktype-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5370

      @tanstack/directive-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5370

      @tanstack/eslint-plugin-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5370

      @tanstack/history

      npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5370

      @tanstack/nitro-v2-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5370

      @tanstack/react-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5370

      @tanstack/react-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5370

      @tanstack/react-router-ssr-query

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5370

      @tanstack/react-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5370

      @tanstack/react-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5370

      @tanstack/react-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5370

      @tanstack/router-cli

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5370

      @tanstack/router-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5370

      @tanstack/router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5370

      @tanstack/router-devtools-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5370

      @tanstack/router-generator

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5370

      @tanstack/router-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5370

      @tanstack/router-ssr-query-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5370

      @tanstack/router-utils

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5370

      @tanstack/router-vite-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5370

      @tanstack/server-functions-plugin

      npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5370

      @tanstack/solid-router

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5370

      @tanstack/solid-router-devtools

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5370

      @tanstack/solid-start

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5370

      @tanstack/solid-start-client

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5370

      @tanstack/solid-start-server

      npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5370

      @tanstack/start-client-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5370

      @tanstack/start-plugin-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5370

      @tanstack/start-server-core

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5370

      @tanstack/start-static-server-functions

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5370

      @tanstack/start-storage-context

      npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5370

      @tanstack/valibot-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5370

      @tanstack/virtual-file-routes

      npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5370

      @tanstack/zod-adapter

      npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5370

      commit: edd4f13

    6. Actionable comments posted: 0

      🧹 Nitpick comments (1)
      packages/nitro-v2-vite-plugin/src/index.ts (1)

      118-130: Consider refining the resolution condition for precision.

      The custom resolveId hook correctly redirects h3 imports to h3-v1 for Nitro v2 compatibility. However, the condition importer?.includes('nitropack') uses a broad string match that could match unintended paths.

      Consider making the condition more precise and adding an explanatory comment:

                         {
                           name: 'resolve',
      +                    // Redirect h3 imports to h3-v1 for Nitro v2 compatibility
      +                    // See: https://github.com/nitrojs/nitro/issues/3613
                           resolveId(source, importer) {
                             if (
      -                        (importer?.includes('nitropack') ||
      +                        (importer?.includes('/nitropack/') ||
                                 importer === virtualEntry) &&
                               source === 'h3'
                             ) {
                               return h3
                             }
                             return null
                           },
                         },

      The refined condition uses /nitropack/ to match path segments more precisely, reducing the risk of false positives. The comment documents the purpose and references the related issue.

      📜 Review details

      Configuration used: CodeRabbit UI

      Review profile: CHILL

      Plan: Pro

      📥 Commits

      Reviewing files that changed from the base of the PR and between dc320144a5c1b00e443e54aed29a502f57e362ff and 3ab08790162290f0f07bd23a033a289288ed098e.

      ⛔ Files ignored due to path filters (1)
      • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
      📒 Files selected for processing (5)
      • packages/nitro-v2-vite-plugin/package.json (1 hunks)
      • packages/nitro-v2-vite-plugin/src/index.ts (4 hunks)
      • packages/nitro-v2-vite-plugin/vite.config.ts (1 hunks)
      • packages/start-server-core/package.json (1 hunks)
      • packages/start-server-core/src/request-response.ts (1 hunks)
      🧰 Additional context used
      📓 Path-based instructions (3)
      **/*.{ts,tsx}

      📄 CodeRabbit inference engine (AGENTS.md)

      Use TypeScript in strict mode with extensive type safety across the codebase

      Files:

      • packages/start-server-core/src/request-response.ts
      • packages/nitro-v2-vite-plugin/vite.config.ts
      • packages/nitro-v2-vite-plugin/src/index.ts
      packages/{*-start,start-*}/**

      📄 CodeRabbit inference engine (AGENTS.md)

      Name and place Start framework packages under packages/-start/ or packages/start-/

      Files:

      • packages/start-server-core/src/request-response.ts
      • packages/start-server-core/package.json
      **/package.json

      📄 CodeRabbit inference engine (AGENTS.md)

      Use workspace:* protocol for internal dependencies in package.json files

      Files:

      • packages/start-server-core/package.json
      • packages/nitro-v2-vite-plugin/package.json
      ⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
      • GitHub Check: Preview
      • GitHub Check: Test
      🔇 Additional comments (6)
      packages/start-server-core/package.json (1)

      71-71: LGTM! Version update from aliased h3-v2 to direct h3 package.

      The change from the alias h3-v2 to the direct h3 package at version 2.0.0-beta.5 is correct and aligns with the import updates in request-response.ts. The version bump includes new features like universal fetch handlers and middleware improvements.

      Since h3 v2 is still in beta, ensure that the version bump from beta.4 to beta.5 doesn't introduce breaking changes affecting your usage. Based on learnings, the beta.5 release includes middleware subsystem refactors and new handler types. Test critical code paths that use h3 session, cookie, and request/response utilities.

      packages/start-server-core/src/request-response.ts (1)

      22-22: LGTM! Import path correctly updated.

      The import path change from h3-v2 to h3 aligns with the dependency update in package.json. All imported symbols remain unchanged, ensuring consistent behavior.

      packages/nitro-v2-vite-plugin/package.json (1)

      64-65: LGTM! h3-v1 alias added for Nitro v2 compatibility.

      The h3-v1 alias dependency correctly pins h3 v1 for Nitro v2, allowing it to coexist with h3 v2 used elsewhere in the monorepo. The version range ^1.15.4 is appropriate for stable v1 releases.

      packages/nitro-v2-vite-plugin/vite.config.ts (1)

      12-12: Verify consistency with package.json "main" field.

      Setting cjs: false disables the CommonJS build, but package.json line 43 still declares "main": "dist/cjs/index.cjs". Since the exports field (lines 45-53) only provides an import condition and the package requires Node >=22.12 (line 60), this package is effectively ESM-only.

      Consider either:

      1. Removing the "main" and "module" fields from package.json if CJS support is not needed, or
      2. Keeping cjs: true (default) if legacy tooling compatibility is required.

      Given the modern Node.js requirement, removing the legacy fields is likely the cleaner approach.

      packages/nitro-v2-vite-plugin/src/index.ts (2)

      6-6: LGTM! Correct use of createRequire for ESM module resolution.

      The createRequire import and usage are appropriate for resolving the h3-v1 module path in an ESM context.

      Also applies to: 19-19


      97-97: LGTM! h3-v1 path resolution at build time.

      Resolving the h3-v1 path during the build phase ensures consistent module resolution for the custom resolveId hook.

Sign in to join this conversation.