Skip to content

chore: migrate from @tanstack/nitro-v2-vite-plugin to nitro/vite (nitro v3) #505

@tombeckenham

Description

@tombeckenham

Background

TanStack Start's current hosting docs recommend the new nitro package (v3) with its built-in nitro/vite plugin rather than @tanstack/nitro-v2-vite-plugin:

⚠️ The `nitro/vite` plugin natively integrates with Vite Environments API as the underlying build tool for TanStack Start. It is still under active development and receives regular updates.

https://tanstack.com/start/latest/docs/framework/react/guide/hosting#nitro

`nitro@3.0.260415-beta` is on the `latest` dist-tag. Switching would consolidate the h3 versions in our tree (today we carry h3@1.15.5 via nitropack@2 and h3@2.0.1-rc.14 via @tanstack/react-start), which was one half of the root cause of the `getHeader` SSR collision we hit in PR #504 and worked around with `ssr.external` for `@elevenlabs/elevenlabs-js`.

Scope

Migrate every `@tanstack/nitro-v2-vite-plugin` consumer in the monorepo (6 packages at last count):

  • `testing/e2e`
  • `testing/panel`
  • `examples/ts-react-chat`
  • `examples/ts-solid-chat`
  • `examples/ts-code-mode-web`

Each package.json swaps the dep and each vite.config.ts switches the import:

```ts
// before
import { nitroV2Plugin } from '@tanstack/nitro-v2-vite-plugin'
// ...
plugins: [nitroV2Plugin(), ...]

// after
import { nitro } from 'nitro/vite'
// ...
plugins: [tanstackStart(), nitro(), viteReact()]
```

Open questions / risks

  • `nitro/vite` is marked "under active development" — we should do this on a branch, run `pnpm --filter @tanstack/ai-e2e test:e2e` end-to-end against it, and only merge once the whole test matrix is green.
  • Nitro 3 uses `rolldown` rather than rollup + esbuild for the server build. The double-h3 part of the `getHeader` collision will disappear, but the ElevenLabs SDK still ships its own top-level `function getHeader(…)` (in `core/fetcher/getHeader.js`). If rolldown inlines that into the same scope as h3 v2's `getHeader`, we may need to keep the current `ssr.external` config or add a rolldown equivalent. Verify empirically post-migration.
  • Preset coverage: we use the default node-server preset in e2e/panel and the `bun` preset in the ts-react-chat example. Both are documented for `nitro/vite`, but worth verifying during the migration.

Acceptance

  • All six packages build cleanly (`pnpm --filter '...' build`) under nitro v3
  • `pnpm --filter @tanstack/ai-e2e test:e2e` passes
  • Local dev (`pnpm dev`) still works for `examples/ts-react-chat`
  • Revisit `ssr.external: ['@elevenlabs/elevenlabs-js']` in `testing/e2e/vite.config.ts` (and any new mirror in ts-react-chat if added later) — drop it if rolldown handles the SDK's CJS `getHeader` without collision, keep it with an updated comment otherwise.
  • Remove `@tanstack/nitro-v2-vite-plugin` from all package.json files

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions