1---
2layout: "#src/blog/tags/blog-layout.marko"
3meta:
4 title: One Year with Next.js App Router — Why We're Moving On
5 description: A critique of React Server Components and Next.js 15.
6 keywords: ["webdev", "technical analysis", "opinion"]
7 authors: ["clover caruso"]
8 embed:
9 thumbnail: /open-graph/next-js.png
10 canonical: /blog/webdev/one-year-next-app-router
11date: "Oct 21st, 2025"
12---
13
14fdsaafsdfds
15
16As I've been using [Next.js] professionally on my employer's web app, I find the
17core design of their App Router and [React Server Components] (RSC) to be
18extremely frustrating. And it's not small bugs or that the API is confusing,
19but large disagreements about the fundamental design decisions that Vercel and
20the React team made when building it.
21
22The more webdev events I go to, the more I see people who dislike Next.js, but
23still get stuck using it. By the end of this article, I will share how me and
24my colleagues escaped this hell, seamlessly migrating our entire frontend to
25[TanStack Start].
26
27[Next.js]: https://nextjs.org
28[React Server Components]: https://react.dev/reference/rsc/server-components
29
30<table-of-contents />
31
32<h2#technical-review>A Technical Review: What are Server Components?</>
33
34The pitch of RSC is that components are put into two categories,
35<b.server>"server"</b> components and <b.client>"client"</b>
36components. Server components don't have `useState`, `useEffect`, but can be
37`async function`s and refer to backend tools like directly calling into a
38database. Client components are the existing
39model, where there is code on the backend to generate HTML text and frontend
40code to manage the DOM using `window.document.*`.
41
42> The first disaster: naming!! React is now using the words
43> <b.server>"server"</b> and <b.client>"client"</b> to refer to
44> a very specific things, ignoring their existing definitions. This would be
45> fine, except <b.client>Client</b> components can run on the backend
46> too! In this article, I'll be using the terms <b>"backend"</b> and
47> <b>"frontend"</b> to describe the two execution environments that web apps
48> exist in: a Node.js process and a Web browser, respectively.
49
50This <b.server>Server</b>/<b.client>Client</b> component model
51is interesting. Since built-ins like `<Suspense />` get serialized across the
52network, data fetching can be very trivially modeled with async
53<b.server>server components</b>, and the fallback UI works as if it were
54client-side.
55
56```tsx filename="src/app/[username]/page.tsx" tint="server"
57// For this article, server components will be highlighted in red
58export default async function Page({ params }) {
59 // Page params are given as a resolved promise
60 const { username } = await params;
61
62 // The components `UserInfo` and `UserPostList` will be run at the same
63 // time. Once `UserInfo` is ready, the visitor will see the page with a
64 // `PostListSkeleton` if the post list is not yet ready.
65 return <main>
66 <UserInfo username={username} />
67
68 <Suspense fallback={<PostListSkeleton />}>
69 <UserPostList username={username} />
70 </Suspense>
71 </main>
72}
73
74// Waterfalls are avoided by having multiple components, which
75// are all evaluated at the same time.
76
77async function UserInfo({ username }) {
78 const user = await fetchUserInfo(username);
79 return <>
80 <h1>{user.displayName}</h1>
81 {user.bio ? <Markdown content={user.bio} /> : ""}
82 </>
83}
84
85async function UserPostList({ username }) {
86 const posts = await fetchUserPostList(username);
87 return /* post list ui omitted for brevity */;
88}
89```
90
91If we ignore the 40kB gzipped bundle size of React itself, the above example
92has zero JavaScript for the UI and data fetching &mdash; it just streams the
93markup! For example, the imagined markdown parser within the `<Markdown />`
94component stays on the backend. When an interactive frontend is needed, <b.client>Client
95components</b> can be created by putting them in a file starting with `"use
96client"`.
97
98```tsx filename="src/components/CopyButton.tsx" tint="client"
99"use client"; // This comment marks the file for client-side bundling.
100
101export function CopyButton({ url }) {
102 return <>
103 <span>{url}</span>
104 <button onClick={() => {
105 const full = new URL(url, location.href);
106 navigator.clipboard.writeText(full.href);
107 // omitting error handling, success ui, styles
108 }}>copy</button>
109 </>
110}
111```
112```tsx filename="src/app/q+a/Card.tsx" tint="server"
113export function Card() {
114 return <article>
115 <header>
116 {/* Make the browser import the copy button */}
117 <CopyButton url="/q+a/2506010139" />
118 </header>
119 <p>
120 {/* Process markdown on the backend */}
121 <Markdown content=".........." />
122 </p>
123 </article>
124}
125```
126
127<h2 id="real-world-pitfalls">Real-world Pitfalls of the App Router</>
128
129After quitting [Bun] as a runtime engineer (I implemented [Server Components
130bundling] and [a RSC template][bun-rsc] there), I joined a small company working on the
131front lines: a Next.js app with a Hono backend. The following notes are
132simplifications from the real world problems I've encountered when trying to
133maintain and develop new features. As a result of all of these, everyone's time
134is wasted either working around design flaws, or explaining to each other why
135what should be a non-issue is an immovable object.
136
137[Bun]: https://bun.com
138[Server Components bundling]: https://github.com/oven-sh/bun/blob/67f0c3e016aa479738469adac2b79a1862b88122/src/bake/bake.d.ts
139[bun-rsc]: https://github.com/oven-sh/bun/tree/e7790894d92b730758ecadf971cb935063508dfb/src/bake/bun-framework-react
140
141<h3 id='optimistic-updates'>Optimistic Updates are Impossible</>
142
143The Next.js documentation for performing mutations [does not mention optimistic
144updates][nextjs-updating-data]; it appears this case was not thought about.
145Components rendered by the <b.server>React Server</b>, by design, can
146not be modified after mounting. Elements that could change need to be inside a
147client component, but data fetching cannot happen on the client components,
148even during SSR on the backend. This results in awkwardly small server
149components that only do data fetching and then have a client component that
150contains a mostly-static version of the page.
151
152```tsx filename="src/app/user/[username]/page.tsx" tint="server"
153
154export default async function Page() {
155 const user = await fetchUserInfo(username);
156 return <ProfileLayout>
157 <UserProfile user={user} />
158 </ProfileLayout>;
159}
160```
161```tsx filename="src/app/user/[username]/UserProfile.tsx" tint="client"
162
163"use client"; // Must separate the client code into a second file!
164
165export function UserProfile({ user: initialUser }) {
166 // There are many great state management libraries out there;
167 // for simplicity, this example will use one state cell.
168 const [user, optimisticUpdateUser] = useState(initialUser);
169
170 async function onEdit(newUser) {
171 optimisticUpdateUser(newUser);
172 const resp = await fetch("...", {
173 method: 'POST',
174 body: JSON.stringify(newUser),
175 ... // (headers, credentials, tracing, and more)
176 })
177 if (!resp.ok) /* always remember to test for errors! */
178 }
179
180 return <main>{/* user interface with editable fields... */}</main>:
181}
182```
183
184As more of the page needs interactivity, it gets messier trying to keep the
185static parts truly server-side. On the work app, nearly every piece of UI
186displays some dynamic data. A [`WebSocket`][ws] synchronizes data live as it
187updates (for example, a user card's online state along with their basic
188profile). Since these component setups are harder to understand and maintain
189for engineers, almost all of our pages are entirely `"use client"` with a
190`page.tsx` that defines the data fetching.
191
192A more concrete example of what this looks like in practice with the
193data-fetching library we use at work, [TanStack Query].
194
195[TanStack Query]: https://github.com/tanstack/query#readme
196
197```ts filename="src/queries/users.ts"
198// At work, there is a helper function `defineQuery` for type safety.
199// Fetchers are trivial and can run on the backend or the frontend.
200export const queryUserInfo = (username) => ({
201 queryKey: ['user', username],
202 queryFn: async ({ ... }) => /* fetch data */
203});
204```
205```tsx filename="src/app/user/[username]/page.tsx" tint="server"
206export default async function Page({ params }) {
207 const { username } = await params;
208
209 // There's no global state in the React Server. Since layouts
210 // are executed in parallel, the TanStack `QueryClient` has to
211 // be reconstructed multiple times per route.
212 const queryClient = new QueryClient();
213 await queryClient.ensureQueryData(queryUserInfo(username));
214
215 // HydrationBoundary is a client component that passes JSON
216 // data from the React server to the client component.
217 return <HydrationBoundary state={dehydrate(queryClient)}>
218 <ClientPage />
219 </HydrationBoundary>;
220}
221```
222```tsx filename="src/app/user/[username]/ClientPage.tsx" tint="client"
223"use client";
224export function ClientPage() {
225 const { username } = useParams();
226 const { data: user } = useSuspenseQuery(queryUserInfo(username));
227
228 // ... some hooks
229
230 return <main>
231 {/* ... an interactive web page */}
232 </main>;
233}
234```
235
236This example has to be three separate files because of the rules of server
237component bundling. (The client component needs `"use client"`, and server
238component files often can't be imported on the client due to server-only
239imports.). In the Pages router, this could've been a single file because of the
240tree-shaking that `getStaticProps` and `getServerSideProps` has.
241
242[ws]: https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API
243[nextjs-updating-data]: https://nextjs.org/docs/app/getting-started/updating-data
244
245<h3 id='redundant-fetches'>Every Navigation is Another Fetch</>
246
247Since the App Router starts every page as a server component, with (ideally)
248small areas of interactivity, a navigation to a new page *has* to fetch the
249Next.js server, regardless of what data the client already has available! Even
250with a a `loading.tsx` file, opening `/`, navigating to `/other`, and then
251going back to `/` will show the loading state while it re-fetches the homepage.
252
253The only case this works is for **perfectly static content**, where instant
254navigations and prefetching work great. But **web apps are not static**, they
255have lots of dynamic content. Being logged in affects the homepage, which is
256infuriating because the client literally has everything needed to display the
257page instantly. It's not like the cookies changed.
258
259> **aside**: In further testing on a blank project, I observe cases where the
260> Next frontend code would pre-fetch routes, but **without any real contents**.
261> On the hello world example, this was a 1.8kB RSC payload that pointed to 2
262> different JS chunks 4 separate times. This is just pure waste of our
263> bandwidth and egress, especially considering all of this information is
264> re-fetched when I actually click the link.
265>
266> ```json whitespace="pre-wrap"
267> 1:"$Sreact.fragment"
268> 2:I[39756,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"default"]
269> 3:I[37457,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"default"]
270> 4:I[97367,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"ViewportBoundary"]
271> 6:I[97367,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"MetadataBoundary"]
272> 7:"$Sreact.suspense"
273> 0:{"b":"TdwnOXsfOJapNex_HjHGt","f":[["children","other",["other",{"children":["__PAGE__",{}]}],["other",["$","$1","c",{"children":[null,["$","$L2",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L3",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":"$undefined","forbidden":"$undefined","unauthorized":"$undefined"}]]}],{"children":null},[["$","div","l",{"children":"loading..."}],[],[]],false],["$","$1","h",{"children":[null,["$","$1","KCFxAJdIDH3BlYXAHsbcVv",{"children":[["$","$L4",null,{"children":"$L5"}],["$","meta",null,{"name":"next-size-adjust","content":""}]]}],["$","$L6","KCFxAJdIDH3BlYXAHsbcVm",{"children":["$","div",null,{"hidden":true,"children":["$","$7",null,{"fallback":null,"children":"$L8"}]}]}]]}],false]],"S":false}
274> 5:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]]
275> 9:I[27201,["/_next/static/chunks/ff1a16fafef87110.js","/_next/static/chunks/7dd66bdf8a7e5707.js"],"IconMark"]
276> 8:[["$","title","0",{"children":"Create Next App"}],["$","meta","1",{"name":"description","content":"Generated by create next app"}],["$","link","2",{"rel":"icon","href":"/favicon.ico?favicon.0b3bf435.ico","sizes":"256x256","type":"image/x-icon"}],["$","$L9","3",{}]]
277> ```
278>
279> In review, I found there is actually some content in here: the loading state.
280> Do you see it?
281>
282> ```json
283> ["$","div","l",{"children":"loading..."}]
284> ```
285>
286> It's still a lot of waste, since all of this data gets re-emitted in the
287> actual page RSC.
288
289The solution to this appears to be [`staleTime`][nextjs-stale], but it's marked
290experimental and "not recommended for production". The fact this is a
291non-default afterthought configuration option is embarrassing. Even if we used
292it, you cannot make multiple pages that refer to the same underlying data share
293any of it.
294
295One form of loading state that cannot be represented with the App Router is
296having a page such as a page like a git project's issue page, and clicking on a
297user name to navigate to their profile page. With `loading.tsx`, the entire
298page is a skeleton, but when modeling these queries with TanStack Query it is
299possible to show the username and avatar instantly while the user's bio and
300repositories are fetched in. Server components don't support this form of
301navigation because the data is only available in rendered components, so it
302must be re-fetched.
303
304[nextjs-stale]: https://nextjs.org/docs/app/api-reference/config/next-config-js/staleTimes
305[nextjs-stale-bug]: https://github.com/vercel/next.js/issues/70661
306
307In our Next.js site, we have this line of code on our server component data
308fetchers to make soft navigations faster by skipping the data fetch phase all
309together.
310
311```tsx filename="src/util/tanstack-query-helpers.server.ts" tint="server"
312export function serverSidePrefetchQueries(queries) {
313 if ((await headers()).get("next-url")) {
314 // This is a soft-navigation. SKIP the prefetching to make it faster.
315 // The client might already have this data, and if not, they have the
316 // loading state. Ideally, this server request wouldn't exist -- The
317 // client side has nearly ALL the code since the app is written mostly
318 // as client components. Kind of a design flaw of the App router TBH.
319 return;
320 }
321 // ... data prefetching-logic ...
322}
323```
324
325In addition to this, `loading.tsx` should contain the `useQuery` calls so that
326while the network request for the empty RSC happens, the data is being fetched
327if it actually is needed. In fact, the `loading.tsx` state can just be the
328actual client component, and you'll see the client page.
329
330```tsx filename="src/app/user/[username]/loading.tsx" tint="client"
331"use client";
332export default function PageLoadingSkeleton() {
333 return <ClientPage />;
334}
335```
336
337> At work, we just make our `loading.tsx` files contain the `useQuery`
338> calls and show a skeleton. This is because when Next.js loads the actual Server
339> Component, no matter what, the entire page re-mounts. No VDOM diffing here,
340> meaning all hooks (`useState`) will reset slightly after the request
341> completes. I tried to reproduce a simple case where I was *begging* Next.js to
342> just *update the existing DOM* and preserve state, but it just doesn't.
343> Thankfully, the time the blank RSC call takes is short enough.
344
345<h3 id='layout-restrictions'>Layouts are Artificially Restricted</>
346
347Layouts can perform data fetching, but they can't observe or alter the request
348in any way. This is done so that Next.js can fetch and cache layouts whenever they
349want. In every other framework, layouts are just regular components that have
350no feature difference compared to page components.
351
352Fetching layouts in isolation is a cute idea, but it ends up being silly
353because it also means that any data fetching has to be re-done per layout. You
354can't share a `QueryClient`; instead, you must rely on their [monkey-patched
355`fetch`][nextjs-fetch] to cache the same `GET` request like they promise.
356
357When a coworker asks me about why Next.js rejects some code, I've given up on
358explaining the technical intricacies and just say *"It's a Next.js Skill Issue,
359I'm going to blow it up soon don't worry."* These rules are too hard for normal
360developers to understand.
361
362[nextjs-fetch]: https://nextjs.org/docs/app/api-reference/functions/fetch
363
364<h3 id='rsc-payload'>You Still Download All the Content Twice</>
365
366Unlike the ["Islands Architecture"][islands], Server Components still have to
367be hydrated on the frontend to support `Suspense` and preserving client
368component state. When doing soft navigations, the "RSC Payload" (which is not
369HTML at all) is retrieved by `fetch`. On a fresh reload, HTML is needed for the
370[first paint], but the information about Client components and `Suspense` is
371not contained within that HTML. React's solution is to **send a second copy of
372the entire page's markup**. An example of what a Next.js production server
373would send in a dynamic page render would be something like this:
374
375[first paint]: https://web.dev/articles/fcp
376
377```html filename="GET /user/clover"
378<!DOCTYPE html>
379<html>
380<head>
381 {link and meta tags}
382</head>
383<body>
384 {server side render}
385 <script>
386 // a bootstrap script that sets up global `__next_f` as
387 // an array. once React loads, this `.push` function
388 // gets overwritten to write new chunks directly to the
389 // RSC decoder. this script has some dom helpers too
390 (self.__next_f=self.__next_f||[]).push([0])
391 </script>
392 <script>
393 // the RSC payload for the application shell.
394 self.__next_f.push([1,"1:\"$Sreact.fragment\"\n2:I[658993,[\"/_next/st{...}"])
395 </script>
396
397 <!--
398 the closing </body> is NOT written yet, since there is a
399 suspense boundary not resolved. time passes, and only
400 then is more data is written
401 -->
402 <div class="user-post-list">
403 {server side render of a Suspense boundary}
404 </div>
405 <script>
406 // the RSC payload for the suspense boundary
407 self.__next_f.push([2,"14:[\"$\",\"div\",null,{\"children\":[[\"$\",\"h4\"{...}"])
408 </script>
409
410 <!-- HTML and script tags repeat until the entire page is done -->
411</body>
412</html>
413```
414
415This solution **doubles the size of the initial HTML payload**. Except it's
416worse, because the RSC payload includes JSON quoted in JS string literals,
417which is a is much less efficient format than HTML. While it seems to compress
418fine with brotli and render fast in the browser, this is wasteful. With the
419hydration pattern, at least the data locally could be re-used for interactivity
420and other pages.
421
422Even on pages that have little to no interactivity, you pay the cost. To use
423the Next.js documentation as an example, loading [its
424homepage](https://nextjs.org/docs) loads an page that is around 750kB (250kB of
425HTML and the 500kB of script tags), and content is in there twice.
426
427You can verify that by pressing <kbd>Cmd</kbd> + <kbd>Opt</kbd> + <kbd>u</kbd>
428on Mac or <kbd>Ctrl</kbd> + <kbd>u</kbd> on other platforms. And then
429<kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + <kbd>f</kbd> to locate any string of the
430blog, such as "building full-stack web applications". It's there twice. And
431**there is no way around this**, since it's a fundamental piece of React Server
432Components.
433
434This RSC format certainly has more waste. But I really don't feel like digging into
435why the string `/_next/static/chunks/6192a3719cda7dcc.js` appears 27 separate
436times. What the hell, guys? Is your bandwidth free???
437
438[islands]: https://www.patterns.dev/vanilla/islands-architecture/
439
440<h3 id='turbopack'>Turbopack Sucks</>
441
442This section is not constructive.
443
444- Turbopack isn't fast
445- Turbopack emits code that is hard to debug in a debugger (in development mode)
446- Turbopack throws bad error messages in many cases
447
448I wouldn't have given this point a section in the blog normally, but I want to
449point out three actual examples directly from the project.
450
451The first is a place where during some refactoring to satisfy the Server/Client
452component models, I accidentally made a Client component `async`. This one was
453quite annoying because it didn't say at all where the issue was, but only
454contained the <b.server>server</b> stack trace.
455
456![Next.js error](/file/2025/blog-everyone-hates-nextjs/asyncerror.png)
457
458Another case of a terrible error message:
459
460![Next.js error](/file/2025/blog-everyone-hates-nextjs/nexterror.png)
461
462> After fixing the underlying issue in this second error (which I cannot recall),
463> the Dev server hung and had to be restarted to recover.
464
465The final one is the dozen times I place a debugger breakpoint and the
466variable name `hello` gets turned into
467`__TURBOPACK__imported__module__$5b$project$5d2f$client$2f$src$2f$utils$2f$filename$2e$ts__$5b$app$2d$client$5d$__$28$ecmascript$29$__["hello"]`
468and other bullshit.
469
470Okay. This all sucks. What can we do?
471
472<h2 id='ditching-nextjs'>Seamlessly Ditching Next.js and Vercel at Work</>
473
474There are two types of web projects:
475
476- A web site with mostly static content.
477- A web app with majorly dynamic and interactive components.
478
479And Next.js is the wrong tool for both of these jobs. If you're in the first
480category with a static web site, go for [Astro] or [Fresh]. For everyone who
481needs the full power of React, this section is about how I replaced the vendor
482locked Next with [TanStack Start], incrementally and seamlessly.
483
484[Astro]: https://astro.build/
485[Fresh]: https://fresh.deno.dev/
486[TanStack Start]: https://tanstack.com/start/latest
487
488It started with this Vite config.
489
490```ts filename="vite.config.ts"
491const config = defineConfig(({ mode }) => {
492 const env = loadEnv(mode, process.cwd(), "NEXT_PUBLIC_");
493 return {
494 // Use the Next.js default port 3000
495 server: { port: 3000 },
496 // Use the Next.js default env prefix "NEXT_PUBLIC_"
497 define: Object.fromEntries(Object.entries(env).map(
498 ([k, v]) => [`process.env.${k}`, JSON.stringify(v)])),
499 plugins: [
500 viteTsConfigPaths({ projects: ["./tsconfig.json"] }),
501 tailwindcss(),
502 // For ease of understanding from coworkers, I started porting
503 // the routes in `src/tanstack-routes`. When the migration was
504 // done, it would go back to the default `src/routes`.
505 tanstackStart({
506 router: { routesDirectory: "src/tanstack-routes" },
507 }),
508 viteReact(),
509 ],
510 resolve: {
511 // The key to the incremental migration: redirect `next` elsewhere
512 alias: { next: path.resolve("./src/tanstack-next/") },
513 conditions: ["tanstack"],
514 extensions: [
515 // Allow a file named like `utils/session.tanstack.ts` to
516 // override `utils/session.ts` when imported.
517 ".tanstack.tsx", ".tanstack.ts",
518 // Default import extensions
519 ".mjs", ".js", ".mts", ".ts",
520 ".jsx", ".tsx", ".json",
521 ],
522 },
523 };
524});
525```
526
527Then, I looked for every usage of a Next.js API, and either removed it or made
528a stub for TanStack. For example, `src/tanstack-next/link.tsx` implements
529`next/link`:
530
531```tsx filename="src/tanstack-next/link.tsx"
532import { Link } from "@tanstack/react-router";
533import type { LinkProps } from "next/link";
534
535export default function LinkAdapter({ href, ...rest }: LinkProps) {
536 return <Link {...rest} to={href as unknown as any} />;
537}
538```
539
540> Some of these stubs can be extremely simple. Starting out, my implementation
541> of `useRouter` was just `return {}`, but later I had to add a couple methods
542> to the object. The code here doesn't have to be clean, because it is
543> temporary.
544
545Now, the new site can import nearly every client component by either stubbing
546out the Next.js APIs it needs, or by using the `.tanstack.ts` extension to
547re-implement logic on a file-by-file basis. And shortly after, I got the site's
548homepage to work in TanStack Start, and we merged the branch.
549
550![My "nextgate" PR](/file/2025/blog-everyone-hates-nextjs/pr.png)
551
552> This first PR only supported one of our pages, and was able to do it in a
553> thousand lines of added code, and 40 lines deleted. I had previous patches to
554> remove the few uses of `next/image` and `next/font`.
555
556What was left was porting every other route over. The one thing we lose in
557migrating from Next.js to any other framework is the ability to `await`
558data-fetching functions in the UI. In practice, moving every route into a
559`loader` function made it much more clear what happened when a page was SSR'd.
560For pages that had multiple fetches, these could be combined into a single,
561special API call that would return all of the relevant data for that page.
562
563To re-iterate in bold font: <strong style='color:var(--secondary)'>The
564migration path from Server Components is to just simplify your code &mdash; RSC
565inherently drives you down a chaotic road of things you do not need</strong>.
566Nearly every complex part of our site got easier to understand for all
567engineers. The exception to this was having everyone get used to the new file
568system routing conventions. With enough examples, we all got the hang of it.
569
570With the incremental migration in place, new code did not break the existing
571deployment. TanStack slowly took over the codebase, and we eventually deleted
572all of the Next.js stubs and gained all of the beautiful [type-safety features]
573that the TanStack Router provides. At the end, the site performed faster from
574every angle: Development Mode, Production page load times, Soft navigations,
575and at a lower price than our Next deployment with Vercel.
576
577[type-safety features]: https://tanstack.com/router/v1/docs/framework/react/guide/type-safety
578
579We're not the only ones seeing the change. While I try and keep myself off of
580social media, someone sent me [the results of Brian Anglin's work at
581Superwall][superwall-twitter], showing incredible CPU reductions on TanStack
582Start. I also recall ChatGPT switching from Next.js to Remix (random online
583chatter: [[1][chatgpt-1]] [[2][chatgpt-2]] [[3][chatgpt-3]]) a year ago.
584
585[superwall-twitter]: https://twitter.com/BriansAngles/status/1978834116079436242#m
586[chatgpt-1]: https://xcancel.com/ryanflorence/status/1831379475654947233
587[chatgpt-2]: https://old.reddit.com/r/reactjs/comments/1f97zgr/chatgpt_migrates_from_nextjs_to_remix
588[chatgpt-3]: https://old.reddit.com/r/nextjs/comments/1f92jdv/chatgptcom_switched_from_nextjs_to_remix
589
590<h3 id='next-metadata'>`next/metadata` is Great</>
591
592In my opinion, this is one of the only good APIs Next.js has, and was the one
593place in our code where moving to TanStack made things harder to do. Instead of
594worsening the code, I just ported their metadata API into a regular function,
595so everyone can use it. Originally, I had a 1:1 port on NPM, but earlier this
596year I simplified it's API into one short and understandable
597file. As of this blog post, I have added a TanStack-compatible
598`meta.toTags` API, which can be installed from [JSR][lib-jsr], [NPM][lib-npm],
599or simply copied into your project.
600
601> **notice**: Due to time constraints with writing this article, the library
602> has not yet been updated. I'll probably get around to it by the ~~end of this
603> week (Oct 24th)~~ some time soon... As a placeholder, I'm able to share the
604> version that is used at work to my website:
605> [`meta.tanstack.ts`](https://paperclover.net/file/2025/blog-everyone-hates-nextjs/meta.tanstack.ts).
606
607```tsx
608// once in your project
609import * as meta from "@clo/lib/meta";
610
611export const defineHead = meta.toTags.bind(null, {
612 // site-wide options
613 base: new URL("https://paperclover.net"),
614 titleTemplate: (title) => [title, "paper clover"]
615 .filter(Boolean).join(' | '),
616 // ...
617});
618
619// for each page...
620export const Route = createFileRoute("/blog")({
621 head: () =>
622 defineHead({
623 title: "clover's blog", // templated with `titleTemplate`
624 description: "a catgirl meows about her technology viewpoints",
625 canonical: "/blog", // joined with `base`
626
627 // When specified, configures Open Graph and Twitter embed,
628 // using the page title and description as the default.
629 // The defaults are good, but it supports more options.
630 embed: {
631 image: "/img/blog.webp",
632 },
633
634 // Every exotic meta tag is done with a JSX fragment. This
635 // doesn't render React, it just loops through the tags.
636 // My goal was to cover the most common 99% of uses.
637 extra: <>
638 <meta name="site-verification" content="waffles" />,
639 </>,
640 }),
641
642 component: Page,
643});
644
645function Page() {
646 ...
647}
648```
649
650My version wasn't concerned with covering the entire space of Next.js's metadata
651object, but instead uses inline JSX to fill that gap.
652
653[lib-jsr]: https://jsr.io/@clo/lib
654[lib-npm]: https://npmjs.com/@paperclover/lib
655
656<h3 id='vercel-og'>`next/og` is Good Too</>
657
658No strong opinions. I just want to remind everyone that the `@vercel/og` package exists.
659
660<h2 id='experience-feels-like-the-usual'>My Experience Feels like the Usual</>
661
662At the Next.js Conf 2024, everyone there was raving about Server Components. I
663forget exactly who I talked to, but the big people were all in on this. I,
664having implemented the bundler end of RSC, saw a couple of the problems in the
665format. With Next 15 "stabilizing" the App Router last year, many companies are
666building their products on it, realizing these pitfalls first-hand.
667
668I came into the Next.js game late, only starting in June with version 15.
669But everyone I've talked to at events sympathize with my notes. All the people
670I talked to on the subject at Bun's 1.3 Party agreed with me. Even some people
671at Vercel told me they don't like how Next.js is to actually use.
672
673I hope as TanStack Start stabilizes, it becomes the Next.js replacement everyone
674wants.
675
676<h2 id='prefer-respectful-tools'>Prefer Tools that Respect You</>
677
678A lot of in the JavaScript ecosystem is a mess. That mess is why web
679development gets made fun of. There were a lot of times I thought that working
680with the web was an unrecoverable mess, but the mess was actually just the
681commonly-used libraries I surrounded myself with. When that is peeled back,
682modern web development technologies are awesome.
683
684I've been making this website from scratch without any framework since late
6852024, by writing systems like my own [TUI progress widget][progress], [static
686file proxy][file-cache], incremental build system, and many more components.
687Working on this code has produced some of my best coding sessions (by
688happiness) in years. The viewers of *[paper clover]* get a better quality
689website; the mini-libraries I create get [extracted for public use][lib],
690everyone wins.
691
692This level of from-scratch is too much for most people, especially at the
693workplace. I say that at the minimum, we should only give our attention and
694money to high quality tools that respect us. And Next.js and the company behind
695it, Vercel, are not that.
696
697If you use Next.js, and feel that the experience doesn't remind you of respect
698too, consider whether you and your colleagues want to continue supporting their
699[serverless empire]. The Vite ecosystem seems pretty decent to build on right
700now, but I still have little experience in using their tools at scale in
701production. The [Vite+ launch from Void0][vite-plus] seems interesting, but
702only time will tell if these venture-funded tools will respect us (end-users
703and developers) long term.
704
705Next.js Conf 2025, as of writing, is [tomorrow][next-conf]. Instead of
706purchasing a $800 ticket, I decided to put that money [toward the TanStack
707team][tanstack-donate] for [respecting and improving the web development
708ecosystem][tanstack-ethos].
709
710[paper clover]: https://paperclover.net/
711[lib]: https://git.paperclover.net/clo/sitegen/src/branch/master/lib#readme
712[progress]: https://git.paperclover.net/clo/sitegen/src/branch/master/lib/progress.ts
713[file-cache]: https://git.paperclover.net/clo/sitegen/src/branch/master/src/file-viewer/cache.ts
714
715[next-conf]: https://nextjs.org/conf
716[vite-plus]: https://viteplus.dev/
717[tanstack-ethos]: https://tanstack.com/ethos
718[tanstack-donate]: https://github.com/sponsors/tannerlinsley
719[serverless empire]: https://youtu.be/SCIfWhAheVw
720
721## What the Future Holds
722
723Slowly, I've been replacing many pieces of software that disrespect me with
724better alternatives. Some examples of this are GitHub, Visual Studio Code,
725DaVinci Resolve, Discord, Google Drive/Workspace, along many more. I plan to
726write more on this blog about the technical things I do (that progress library,
727the purpose of my own site generator, learnings from my current job), including
728some of my past projects at Bun (details on HMR, the crash reporter, and the
729crazy system for bundling built-in modules). If it interests you, please
730subscribe to the email list:
731
732<a href="mailto:subscribe@paperclover.net?subject=paper%20clover%20mailing%20list&body=I%20would%20like%20to%20be%20subscribed%20to%20the%20following%20mailing%20lists%3A%0A%0A-%20Technical%20Blog%20Posts%20-%20YES%0A-%20Art%20(Original%20Music%2FVideo)%20-%20YES%0A%0A(feel%20free%20to%20write%20whatever%20else%20you%20want)">click here to send an email to <code>subscribe@paperclover.net</code>, requesting that you would like to be added to the mailing list.</a> (i manage this mailing list manually)
733
734[back to top](#top) &mdash; [ask a question about this article](/q+a)
735
736<br />
737<br />
738<br />
739<br />
740<br />
741<br />
742<footer>
7432025 (c) paper clover
744</footer>