Start: Client-side router cannot navigate to API route

[jasongitmail]

Which project does this relate to?

Start

Describe the bug

Clicking a Link element that points to an API route always returns "Route not found".

Your Example Website or App

.

Steps to Reproduce the Bug or Issue

1. Create an API route like /api/blog/feed

import { createAPIFileRoute } from "@tanstack/react-start/api";

export const APIRoute = createAPIFileRoute("/api/blog/feed")({
  GET: async ({ request }) => {
    return new Response("Hello! from " + request.url);
  },
});

2. Add a Link element on some view in the app, like this in a footer: <Link to="/api/blog/feed">RSS Feed</Link>
3. Visit homepage and then click the link.

Actual behavior:
Route not found is shown in the UI.

(Hard refreshing when on /api/blog/feed or visiting it directly in the browser loads it, b/c the route itself is working properly.)

Expected behavior:
The server side route's contents should be displayed after clicking a Link to it.

Notes:
The Link element does not find any API/server-side route in its types

Solutions would be to 1.) include all API routes in the types, 2.) only includes API routes that are outside the /api dir, if you wanted to not include all of API routes in the types, when TanstackStart supports locating API routes outside the api dir. But the former would be more expected behavior.

Alternatives considered:

• Using a regular <a href="/api/blog/feed">RSS</a> works. I'll use this for now. But 1.) the link will not benefit from Link's prefetching, 2.) it complicates the DX to need to handle links differently depending on if they link to a view or a server side route.
• You might be thinking it's silly to link to RSS feed in footer. Extrapolate the example to other dynamic files like invoice.pdf, etc.

Expected behavior

.

Screenshots or Videos

No response

Platform

• OS: macOS
• Browser: Chrome, Safari
• Versions

    "@tanstack/react-query": "^5.69.0",
    "@tanstack/react-router": "^1.114.27",
    "@tanstack/react-router-with-query": "^1.114.27",
    "@tanstack/react-start": "^1.114.27",

Additional context

No response

[SeanCassiere]

This is expected behaviour, since the API routes are not navigatable routes via the router. Even if you force this navigation using the Router, you'd have to use the reloadDocument flag, since on-click the Router will evaluate and realize that your /api/** routes aren't accessible by Router.

You should be using the native anchor element for this.

<Link to='/blog'>Blog Route</Link>
<a href='/api/blog/stuff>External route</a>

[jasongitmail]

Expected behavior currently, but a small headache DX wise. For example, if you're rendering a list of links from an array, likely passed as a prop to a component, your template now must contain conditional logic to use an a or Link, depending on the destination.

(My perspective is coming from SvelteKit where this "just works" irrespective of the link destination.)

Low priority since there is an easy workaround

[schiller-manuel]

(My perspective is coming from SvelteKit where this "just works" irrespective of the link destination.)

is this a typesafe link there?

[jasongitmail]

No, but that's orthogonal given it should be possible to make it typesafe here for API routes.

There are much higher priorities for Tanstack right now. Just creating the issue to note a DX rough edge to consider down the road.

[schiller-manuel]

we are currently reworking API routes while migrating off vinxi, and we discussed exactly this. Since for API routes we won't have router level path and search param validation, a fully typesafe link won't be possible. We decided not to bring in API routes into <Link>, neither in types, nor at runtime.

[SeanCassiere]

Closing with Manuel's reasoning from about.