Runtime baseURL

[johnf]

Is it possible to set the baseURL at runtime via an environment variable?

My use case is creating a TanStack Start app that can be dockerised and then mounted behind a proxy at any subpath

[apoorva-01]

Yeah, set NITRO_APP_BASE_URL at runtime. Nitro's app.baseURL defaults to /, or that env var if you provide one, and it's read at runtime, so you don't have to bake the subpath in at build time.

For a dockerised TanStack Start app behind a proxy at some subpath, that's exactly the case it covers:

docker run -e NITRO_APP_BASE_URL=/my-subpath/ your-image

Keep the leading and trailing slashes (/my-subpath/), that's the format Nitro expects for baseURL and it keeps your asset URLs joining correctly.

[johnf]

@apoorva-01 Are you sure? My testing seems to indicate that it only influences the pnpm build step

[Meliceanu]

Setting it at build time works, but the env var isn't build-only. The catch is that "baseURL" is really two different things here.

Server side: NITRO_APP_BASE_URL is honored at runtime. Build with the default base, then start the built server with NITRO_APP_BASE_URL=/my-subpath/ and Nitro mounts every route under /my-subpath/, so the prefixed paths respond and the bare ones 404. For a plain Nitro server the env var does what you want at runtime.

Client side: this is what breaks a TanStack Start (or any Vite) app. Vite's base is applied at build time and baked into the generated HTML/JS as absolute URLs (/base/assets/xxx.js). Starting Nitro under a different runtime base doesn't rewrite those, so the browser keeps requesting assets at the build-time path and the app 404s its own chunks. That mismatch is why it looks like only the build step reacts to the base.

For "one image, mounted at any subpath decided at runtime":

• If the subpath is fixed per deployment, build with that base (Vite base plus your router basepath for that environment). Simplest and most robust.
• If you truly need a single build that adapts at runtime, Vite has an experimental hook for exactly this, experimental.renderBuiltUrl, which lets you return a runtime expression instead of a static base:

  experimental: {
    renderBuiltUrl(filename, { hostType }) {
      if (hostType === 'js') return { runtime: `window.__assetsBase(${JSON.stringify(filename)})` }
      return { relative: true }
    }
  }

  You wire window.__assetsBase (and the router basepath) from a value injected at container start. More moving parts, but it's the supported way to defer the base to runtime.
• Otherwise, a reverse proxy that strips the subpath before Nitro is the low-effort escape hatch.