Cannot implement SPA fallback routing: HTML bundle serialized as JSON in onError

[SpeedySH]

What version of Elysia is running?

1.4.13

What platform is your computer?

Linux 6.6.87.2-microsoft-standard-WSL2 x86_64 x86_64

What environment are you using

1.3.1

Are you using dynamic mode?

NO

What steps can reproduce the bug?

Goal: Implement a full-featured SPA with client-side routing following the https://elysiajs.com/patterns/fullstack-dev-server.html

Step 1: Try to return the Bun HTML bundle for all routes that are not defined as API endpoints using onError:

  import index from '@public/index.html'

  new Elysia()
    .use(staticPlugin({ assets: "public", prefix: "/" }))
    .mount("/api", auth.handler)
    .onError(({ code, request }) => {
      if (code === "NOT_FOUND") {
        return index; // Attempt to return HTML bundle
      }
    })

Step 2: Navigate to any non-existent route like /projects/123

What is the expected behavior?

The server should return the HTML bundle (served via Bun's native HTML bundler) for all unmatched routes, allowing the client-side router to handle navigation. This is the standard SPA fallback pattern.

Bun's Native Router already supports this feature out of the box, so Elysia should be able to leverage it when returning HTML files.

What do you see instead?

Problem 1: onError serializes HTML as JSON

When returning the HTML bundle from onError, Elysia attempts to serialize it as JSON instead of serving it as an HTML document. The browser receives JSON instead of rendered HTML.

Problem 2: Wildcard route get('/*') doesn't work with .use() or .mount()

The traditional solution of using a wildcard route also fails:

.get('/*', () => index)

This approach has a critical limitation: it only handles single-level routes. Any routes defined via .use() or .mount() (like /api/auth/* from better-auth) get overridden by the wildcard, causing 404s on legitimate API endpoints.

The wildcard pattern doesn't respect the plugin aggregation hierarchy when using .use().

Additional information

Current workaround (hacky solution):

  .onError(({ code, request }) => {
    if (code === "NOT_FOUND") {
      const url = new URL(request.url);
      const returnPath = url.pathname;

      // Redirect to root with return path in query params
      if (returnPath !== "/" && returnPath !== "/login") {
        return redirect(`/?return=${encodeURIComponent(returnPath)}`);
      }

      return redirect("/");
    }
  })

This forces all unknown routes to redirect to / with a query parameter, then client-side code reads the ?return= param and navigates to the intended path. This is unreliable and breaks direct navigation.

Expected solution:

Either:

1. Fix onError to correctly return HTML bundles as HTML (not JSON) when the file type is .html
2. Improve wildcard route matching to respect .use() and .mount() plugin routes (path priority: API endpoints → static files → wildcard fallback)

Have you try removing the node_modules and bun.lockb and try again yet?

YES

[mrctrifork]

Quick note: you don't return index from your handler. index IS your handler. It's very unintuitive. So if you see bun's examples you'll see:

serve({ 
  routes: {
    '/': index,
    '/api/hello': () => ({ hello: 'world' })
  }
})

If you want to mimic that behavior in Elysia you'd have to:

new Elysia()
  .get('/', index)
  .listen(3000)

But yeah — it's still not gonna work.

I think Elysia's routing internals or Elysia's static plugin are either very broken or behave in a very unintuitive way. I've been going at this problem for hours during the past week and I've spent two hours just to end up using Bun's native server instead:

serve({
  routes: {
    '/api/auth/*': auth.handler,
    '/*': index
  }
})

I've found this issue from someone else trying to tackle the same problem in opposite direction

---

In a separate pet project of mine I had to do the following dance to get Elysia to correctly use a fallback (Bun's full stack devserver was not there yet):

function acceptsJSON(request: Request) {
  return request.headers.get('accept')?.includes('application/json')
}

export function shouldFallbackToSPA<TCode extends string>({ code, request }: { code: TCode | number, request: Request }) {
  const isNotFound = (code === 'NOT_FOUND' || code === 404)
  return isNotFound && !acceptsJSON(request)
}



export async function serveFrontend(request: Request) {
  const url = new URL(request.url)
  const filePath = url.pathname === '/' ? '/index.html' : url.pathname
  const fullPath = path.join(env.FRONTEND_PATH, filePath)
  const indexPath = path.join(env.FRONTEND_PATH, 'index.html')

  try {
    const file = Bun.file(fullPath)
    const exists = await file.exists()

    if (!exists) {
      // For SPA routing, serve index.html for non-existent paths
      return Bun.file(indexPath)
    }

    return file
  } catch (error) {
    log.error("Error serving frontend", { error });
    return undefined
  }
}


export const spaPlugin = new Elysia()
  .onError({ as: 'global' }, async ({ set, code, error, request }) => {
    // Let SPA take over.
    if (shouldFallbackToSPA({ code, request })) {
      const resp = await serveFrontend(request)
      if(resp) {
        const bytes = await resp.bytes()
        log.debug("Fallback to SPA", { 
          length: bytes.length,
          type: resp.type,
        });
        return new Response(bytes, {
          status: 200,
          headers: {
            'Content-Type': resp.type,
            'Content-Length': bytes.length.toString(),
          }
        })
      }
     // Other logic you might wanna have
    }

[tuliocll]

Quick note: you don't return index from your handler. index IS your handler. It's very unintuitive. So if you see bun's examples you'll see:

this saved me, thanks a lot @mrctrifork!

I was having a problem with my SPA routes (React Router) not rendering, but it's fixed now.

import index from '@public/index.html'


export const app = new Elysia()
  .use(executionRouter)
  .use(
    staticPlugin({
      prefix: "/",
      alwaysStatic: true,
    })
  )
  .get("/*", index);

[a-rebets]

Hey guys,

Regarding the issues with SPA serving - I recently made a template which uses Elysia and Svelte on the frontend.

https://github.com/a-rebets/buffet

In case you need some patterns / to see an example in action.

The big issue is that I indeed struggled with making HTMLBundle work as a handler properly. I made a simple test where I had one catch-all route like .get("/*", indexHtml) and a more narrow one like .get("/api/check/*", handler). The routes are both wildcard type, so the one registered first should win. It was not the case.

Verified that the static plugin can't be a suspect, then launched the Codex model to dig in the Elysia source code and do experiments with eval. It found the most likely reason stuff is breaking and a workaround.

Now, being clear here - it's an AI generated report so I'm sorry for inaccuracies and the amount of text. Adding it in the next message 🫡

[a-rebets]

@SaltyAom

Report: nativeStaticResponse bypasses dynamic routes when using HTML bundles

Environment

• Bun 1.3.2
• Elysia (latest as of today)
• SPA fallback served via HTML import (Bun’s HTMLBundle)

Symptoms

Mounting an API plugin under /api and a catch-all SPA fallback (/*) works until the app is compiled with { nativeStaticResponse: true } (default). Every GET under /api/* returns the SPA HTML instead of hitting the Elysia router.

Root Cause

When nativeStaticResponse is enabled, Elysia caches non-function handlers into app.router.response. During BunAdapter.listen, those cached responses are merged into the Bun server routes.

Key code paths:

1. Static handler caching
   src/index.ts

const nativeStaticHandler =
  typeof handle !== "function"
    ? () => {
        // ...
        const fn = adapter.createNativeStaticHandler?.(
          handle,
          hooks,
          context.set as Context["set"],
        );
        return fn instanceof Promise ? fn.then((fn) => fn) : fn?.();
      }
    : undefined;

const addResponsePath = (path: string) => {
  if (!this.config.nativeStaticResponse || !nativeStaticHandler) return;
  if (supportPerMethodInlineHandler) {
    this.router.response[path] ??= {};
    this.router.response[path]![method] = nativeStaticHandler();
  } else {
    this.router.response[path] = nativeStaticHandler();
  }
};

addResponsePath(path);

2. HTMLBundle passthrough
   src/adapter/bun/handler-native.ts

export const createNativeStaticHandler = (
  handle: unknown,
  hooks: AnyLocalHook,
  set?: Context["set"],
) => {
  if (typeof handle === "function" || handle instanceof Blob) return;
  if (isHTMLBundle(handle)) return () => handle as any;
  const response = mapResponse(handle, set ?? { headers: {} });
  // ...
};

3. Routes forwarded to Bun
   src/adapter/bun/index.ts

const createStaticRoute = (iterator: AnyElysia["router"]["response"]) => {
  const staticRoutes: Record<string, Response | Record<string, Response>> = {};
  for (let [path, route] of Object.entries(iterator)) {
    path = encodeURI(path);
    if (!route) continue;
    for (const [method, value] of Object.entries(route)) {
      if (!value || !(method in supportedMethods)) continue;
      if (
        value instanceof Response ||
        isHTMLBundle(value)
      ) {
        (staticRoutes[path] ??= {})[method] = value;
      }
    }
  }
  return staticRoutes;
};

// ...

routes: mergeRoutes(
  mergeRoutes(
    createStaticRoute(app.router.response),
    mapRoutes(app),
  ),
  app.config.serve?.routes,
);

Because the SPA fallback ultimately places the HTMLBundle under GET /*, Bun’s router serves that bundle before the dynamic fetch handler can run. Any subpath (/api/auth/get-session) is swallowed by the static route, so the dynamic router never fires. Disabling nativeStaticResponse stops Bun from hijacking, but you lose the bundling benefit.

Workaround

Explicitly override the affected prefix in Bun’s routes table so requests fall through to fetch:

const app = new Elysia({
  serve: {
    routes: {
      "/api/*": false,
    },
  },
})
  .use(apiRouter)
  .use(staticPlugin(...))
  .get("/*", indexHtml);

Setting /api/*: false tells Bun “no inline response here,” so /api traffic reaches the Elysia router while the SPA bundle stays intact.

Suggested Improvements for Elysia

Automatic carve-out: When nativeStaticResponse is enabled, Elysia could prepopulate serve.routes with false for any registered plugin prefix (e.g., /api/*), preventing accidental takeover

[dodiz]

doesn't work for me

const apiRouter = new Elysia({
	prefix: '/api'
}).get('/', () => 'api route')

const app = new Elysia({
	serve: {
		routes: {
			'/api/*': false
		}
	}
})
	.use(apiRouter)
	.get('/*', index)
	.listen(3000)

accessing to http://localhost:3000/api returns the html bundle
accessing to http://localhost:3000/api/ works tho

[a-rebets]

@dodiz yes because trailing slash is important, if you add a route with / you get /api/ mounted to the resulting instance

[Cryxto]

If anyone still encounter this issue, i kinda managed make it work even i have prefix api for my api + can work with better auth where better auth is still under api prefix but the frontend spa can be in root and spa routes work flawlessly. I cannot show full code because it is an internal app but maybe if i have time i can give example full app. But for now here the work around .

my frontend build is on public where the html located in public/index.html and all assets (may contain js that handle spa routes too) is in public/assets/*, what i do is place my main api routes, then staticPlugin , then we handle not found (for fallback like when we refresh current spa routes) by returning our html file. My spa is using react router v7 with ssr off

new Elysia()
        .use(
          cors({
            origin: ['http://localhost:5173', 'http://localhost:3001'],
            credentials: true,
          }),
        )
        .use(server) //primary main server routes that contain all controller, auth, etc
        .use(
          staticPlugin({
            assets: './public/assets',
            prefix: '/assets',
            alwaysStatic: true,
          }),
        )
        .get('/', () => file('./public/index.html'))
        .onError(({ code, path, set }) => {
          // Serve SPA for 404s that aren't API or asset requests
          if (code === 'NOT_FOUND' && !path.startsWith('/api/') && !path.startsWith('/assets')) {
            set.status = 200;
            return file('./public/index.html');
          }
        })
        .listen(3000);

[a-rebets]

@Cryxto could you edit the code to leave only the parts related to Elysia and this issue? I don't understand anything

[Cryxto]

@a-rebets done

[SpeedySH]

oven-sh/bun#17595
oven-sh/bun#17363

this two is blockers for easy to implement SPA.

[nofxboy1234]

Could the below issue maybe be contributing to the cause of this issue?:
oven-sh/bun#23999