Custom server support for TanStack Start

[TrevorBurnham]

I'm considering migrating a project from Next.js to TanStack Start, but I've hit a roadblock: I'm running Next.js behind an Express.js server for various middleware, which Next.js makes straightforward with their custom server feature. I don't see any analogous way to run TanStack Start within an existing Node.js process.

This may be a limitation of Vinxi, which can be started programatically but doesn't have any way to route calls to it programmatically AFAICT. Perhaps this feature could be added to the roadmap as a goal to achieve when moving away from Vinxi?

My use case may be a bit niche, but I imagine that being able to run behind Express.js would make gradual migration away from Next.js easier for lots of folks: You could have Express.js send requests for supported routes to TanStack Query and send all other requests to the old Next.js server as a fallback.

[TheOrdinaryWow]

I think this is needed. I want to use rust as a backend, so it'd be great to integrate with custom server.

[delambo]

This is also a requirement in our investigation for a nytimes.com framework replacement. A custom server is a must for enterprise sites.

[schiller-manuel]

this should already work with the node preset: https://nitro.build/deploy/runtimes/node#handler-advanced

[delambo]

Thanks for the info! From my investigation, Nitro is going away? Will that mean that the Vite server.js file will be the application server for Tanstack Start in the future, or a similar integration?

[schiller-manuel]

nitro will go away at runtime, but will still be used for building the deployment artifacts. however i think for the custom server case, we could just not use nitro at all (not even for building). let me think some more about that.

[danny-avila]

Hi @schiller-manuel 👋

For the time being, can you give a minimal example of how to use the node preset, in particular for an Express.js server for various middleware as OP raised?

We have the same use case, it would be a great benefit to immediately re-use our existing, battle-tested authentication middleware, rather than maintain for 2 separate frameworks.

[danielroe]

for what it is worth, nitro supports custom presets, where you can provide exactly the server entrypoint you want

[CanRau]

I'm a little lost on what the next version will allow after DeVinxi and newer to me even kinda de-nitro, at least at runtime?

Anyway, similar to op when going to probably adopt TSS some point after the current alpha is more stable and I find the time I'd love to incrementally migrate our currently Rakkas based app and having a custom router for this would be pretty helpful serving everything already migrated from tss and the rest from rakkas. While I wanted to share that I have this use-case as well I wanted to take this discussion as an opportunity to share some strategies I think are pretty elegant and flexible

Inspired by RedwoodSDK docs

export default defineApp([
  // Middleware
  function middleware({ request, ctx }) { /* Modify context */ },
  function middleware({ request, ctx }) { /* Modify context */ },
  // Request Handlers
  route("/", function handler({ request, ctx }) {
    return new Response("Hello, world!")
  }),
  route("/ping", function handler({ request, ctx }) {
    return new Response("Pong!")
  }),

  handleFileRoutes(),

  // if no file route matched continue
  function middleware({ request, ctx }) {
    // delegate to old app, NextJS, Rakkas, whatever
  },

  // or alternatively or maybe even in addition
  async function middleware({ request, ctx }) {
    const fileRoute = await handleFileRoutes();
    const fileRouteResponse = await fileRouteResponse;
    if (fileRouteResponse.status === 200)
     return fileRouteResponse;
    }

    // delegate to old app like NextJS, Rakkas, whatever
  },
]);

handleFileRoutes() is not part of rwsdk, just a personal idea I think could be very powerful so you can basically chain middlewares, routes (basically api endpoints) and then let the file router take over if nothing else returned anything before

Also rwsdk addons are pretty cool which hook into the above example https://rwsdk.com/blog/full-stack-colocation

And similar to Rakkas, Vike lets you define a custom server where you can do things and then let the app take over.

Also what I really like about the new devinxi'd tss is not only server routes anywhere but even in the same file as an app route code example 👌

[darkobits]

I, like @CanRau, am also a little confused as to the ultimate direction TanStack Start is going with respect to its server following the De-Vinxi effort.

My use-case is WebSockets.

When it was still Vinxi-based, it was possible to set up a router for a WebSocket handler by modifying the vinxiApp instance directly:

app.config.ts

import { defineConfig } from '@tanstack/react-start/config'

defineConfig({
  // TanStack Start config
}).then(vinxiApp => {
  return vinxiApp.addRouter({
    name: 'websocket',
    type: 'http',
    target: 'server',
    base: '/api/ws',
    handler: 'app/routes/api/ws.ts'
  })
})

Post De-Vinxi, it now appears that Nitro is still being used, but there is no straightforward way to hook into or modify its configuration. And, it looks like TanStack Start now uses Vite's dev server instance directly for local development, and then builds its Nitro server for production only.

This makes it challenging to build any kind of unified plug-in / solution to enable robust WebSocket support, though I was able to put together a Vite plug-in that might address the dev component, but it's not clear how one would solve for this with the production server.

If my understanding is correct, there is even a plan to move off of Nitro, but to what I do not know, so I'm not sure what tools / APIs / plug-in systems I should be trying to target / work with at the moment.

If there happens to be any documentation on this subject that outlines the vision for the 'server story', I'd greatly appreciate a link!

Overall, very impressed with TanStack Start thus far; it feels like a generational leap over Next.js. 🎉

[fabb]

We'd need that too. We have existing next.js apps with custom express.js servers, and it would be much more convenient to just add tanstack start as a middleware on some paths for gradual migration, than having to set up a completely separate application with an own ingress (and having to implement our needed middlewares like auth there again).

[schiller-manuel]

we are on it

[fabb]

Very nice, looking forward to it!

Please design it similar to the next.js middleware that handles hot module reload and react fast refresh automatically in dev mode, and not like the astro middleware that requires a rebuild of the server on every change.

[schiller-manuel]

this will use vite dev server in middleware mode so I guess this will just work