1. TanStack Start as the framework

Context

The original build specification described the frontend as Next.js, and that description is still in the repository's README.md. The application was not built that way.

The requirements were server-side rendering for public profile pages that should be shareable and indexable, file-based routing, and a data-fetching layer that suited an application talking directly to a database API rather than to a custom backend.

Decision

TanStack Start, on top of TanStack Router, with TanStack Query for data fetching.

The deciding factor was that this application's data layer is Supabase queried directly from components. TanStack Query is the natural fit for that pattern, and TanStack Start integrates with the same router and the same caching model rather than pulling in a second, parallel data-fetching system.

Consequences

The README is wrong and should not be trusted on this point. Anyone arriving from that file will look for pages/, getServerSideProps, and Next-style layouts, none of which exist. This is a documented trap rather than a fixed one.

Patterns from Next.js documentation do not transfer. Routing, data loading, and the server entry point all work differently. Search for how this repository does something before importing a pattern from elsewhere.

The ecosystem is smaller. There are fewer examples, fewer answered questions, and fewer libraries that assume this framework. When something is unusual, the source is often the fastest documentation.

Some framework behaviours are surprising and are worked around in this repository. The server entry is wrapped to recover error details that the underlying server layer otherwise discards, and that wrapping is wired up deliberately in the Vite configuration. Removing it makes production errors unreadable.

Scroll restoration is handled by the router, keyed to history entries, which interacts with in-app navigation in ways worth understanding before building any control that behaves like a back button.