Josip Papež

As the React ecosystem continues to evolve, developers are faced with increasingly sophisticated framework options for building modern web applications.


Two contenders stand out in 2025: Next.js, the established industry standard now at version 15, and TanStack Start, the emerging challenger (still in Beta) built by the team behind the popular TanStack libraries.


This comprehensive comparison explores how these frameworks stack up against each other, their distinctive approaches to full-stack React development, and which one might be the best fit for your next project.



Architectural Philosophy: Client-First vs Server-First


The fundamental difference between these frameworks lies in their architectural approach to web application development.



TanStack Start: Embracing Client-Side Flexibility


TanStack Start positions itself as a framework optimized for single-page applications (SPAs) that require heavy client-side interactivity with opt in SSR features[1].


Built on TanStack Router and powered by Vite/Nitro[2], it introduces a unique hybrid approach:


 * Full-document SSR with streaming and hydration enables progressive loading of complex UIs[3]
 * Server functions operate as type-safe RPC endpoints callable from any client component[3:1]
 * File-system routing with compile-time type checks for route parameters[3:2]
 * Virtual file routes allowing programmatic route tree construction referencing real files, useful for custom structures or integrating existing file layouts[4]
 * Code-based routing for defining the entire route tree in code, offering granular control but generally less recommended than file-based approaches[5]


As Tanner (TanStack's creator) explained, he plans to utilize React Query to interact with React Server Components (RSC) "as if it were an API" - viewing RSC primarily as "an API that returns JSX instead of JSON."


This perspective simplifies the architectural mindset for developing SPAs while leveraging server capabilities when necessary.



Next.js: The Server-First Pioneer


Next.js operates on a server-first routing model[6], where client components are processed server-side before being sent to the client[7]. With version 15, Next.js has strengthened its position with:


 * Partial prerendering combining static and dynamic components together in the same route[8]
 * Server Actions providing RSC-compatible mutations[9]
 * Metadata API simplifying SEO management through file-based configuration[10]
 * React 19 support with hydration error improvements[11]
 * Stable Turbopack for development performance[12] [13]


However, some developers report friction when building complex SPAs with Next.js, finding it frustrating that client components cannot directly import server components.


Additionally, RSC responses can be quite large, leading to complete page re-renders even when only minor changes occur.



Type Safety: The Developer Experience Factor



TanStack Start's Type-First Approach


One of TanStack Start's most compelling features is its emphasis on end-to-end type safety:


 * Route validation generates TypeScript definitions for path parameters[14]
 * Server function contracts ensure input/output types propagate to client callsites[3:3]
 * Native Query integration with server/client data hydration


This approach significantly reduces runtime errors.


The framework enforces a strict but type-safe layout that provides developers with confidence in their code.



Next.js Type Support Evolution


While Next.js 15 has improved TypeScript support, there are still gaps that require attention:


 * Dynamic route segments often require manual type assertions
 * Server Actions lack automatic input validation
 * fetch responses need explicit typing despite React 19 improvements


These limitations can introduce additional boilerplate code compared to TanStack Start's automated approach with generated routing types.



Developer Experience: The Daily Workflow



TanStack Start: Explicit and Transparent


TanStack Start emphasizes transparency and explicitness in its architecture[15]:


📁app/
├── 📁 routes/
│ ├── 📄 __root.tsx # Root layout and configuration
│ └── 📄 index.tsx # Individual routes
├── 📄 client.tsx # Client-side entry
├── 📄 router.tsx # Router configuration
└── 📄 ssr.tsx # Server-side entry



Developers appreciate that TanStack Start feels "less magical" with much less abstractions compared to Next.js. Everything is described as "super transparent and flexible," making it easier to understand what's happening behind the scenes.


The developer experience is further enhanced by the quality of documentation and devtools offered by the TanStack ecosystem.


For developers already familiar with TanStack libraries like Query and Router, adopting Start feels natural and intuitive.



Next.js: Comprehensive but Complex


Next.js offers a comprehensive development experience with features like:


 * Automated codemods for upgrades (npx @next/codemod@canary upgrade latest)
 * Static indicators showing static routes during development
 * Enhanced forms with client-side navigation
 * TypeScript support for configuration files (next.config.ts)
 * Automated setup using create-next-app[16]


However, the framework has been criticized for making "erratic/magical changes" that can be difficult to understand[17].


As projects grow in complexity, developers may find themselves wrestling with the framework's opinionated approach and frustrated with having to "re-learn a whole framework to use it each time a new version is released".



Community and Ecosystem: Support When You Need It



Next.js: The Established Leader


Next.js boasts a vast community and ecosystem, making it easy to find starter templates and solutions to common problems. This extensive support network is particularly valuable for teams needing quick solutions to technical challenges.


With Vercel's backing, Next.js has established itself as the industry standard for React applications, especially those requiring server-side rendering for SEO purposes.


Its integration with Vercel's platform offers additional benefits like partial pre-rendering, though this has raised concerns about potential vendor lock-in.



TanStack Start: The Growing Challenger


While TanStack Start's community is smaller, it's growing rapidly and consists of developers who are passionate about modern React development approaches.


The quality of available resources is often highlighted, with one user noting, "I think Tanstack will be better than Remix or even Next.js a few updates later. The quality of their docs & the devtools they offer is really good".


Recent developments like the new TanStack React Query integration with tRPC demonstrate the ecosystem's continued evolution and maturation.


However, being a newer framework, TanStack Start does have fewer tutorials, templates, and third-party integrations compared to Next.js even though it is built upon an existing ecosystem/tools.



Deployment Options: From Development to Production



Next.js: Optimized for Vercel, Viable Elsewhere


Next.js offers two primary deployment pathways:


 * Vercel-managed deployment with zero-config optimizations[18]
 * Self-hosting via Node.js servers, Docker, or static exports[19]


Next.js 15 has introduced improvements to self-hosting, giving developers more control over Cache-Control headers. However, some developers report challenges when deploying Next.js applications beyond the Vercel platform.



TanStack Start: Preset-Driven Flexibility


Built on Nitro/Vite, TanStack Start provides over 40 deployment presets via app.config.ts configuration[20][21]. This approach offers flexibility for deploying to various environments without requiring additional adapter packages[1:1].


The framework supports all major deployment platforms including Vercel, Firebase, Cloudflare Pages, AWS Lambda, AWS Amplify, Docker, and Edge Workers.


This flexibility makes TanStack Start an attractive option for teams with specific deployment requirements or preferences.



When to Choose Each Framework



Consider TanStack Start When


 * Building data-intensive dashboards or complex SPAs
 * Needing type-safe server/client contracts
 * Prioritizing client-side interactivity over static content
 * Seeking a more transparent and less "magical" architecture
 * Already using other TanStack libraries (Query, Router, etc.)
 * Wanting flexible deployment options beyond Vercel


One developer who transitioned to TanStack Start shared: "For me tanstack start has most of the features I want out of next, but with waaaaay less magic. Everything is super transparent and flexible".



Stick with Next.js When


 * Developing marketing sites with heavy static content
 * Building SEO-friendly projects like blogs or e-commerce sites
 * Needing turnkey solutions for auth, image optimization, etc.
 * Valuing a large community and abundant resources
 * Requiring enterprise-grade stability and long-term support
 * Planning to deploy primarily on Vercel



The State of React Frameworks in 2025


The choice between TanStack Start and Next.js ultimately depends on your project requirements, team preferences, and development philosophy.


Next.js remains the industry standard with its mature ecosystem, comprehensive feature set, and strong backing from Vercel.


Its server-first approach excels for content-heavy applications where SEO is crucial. However, it comes with some constraints and complexity that can frustrate developers building highly interactive SPAs.


TanStack Start represents a paradigm shift toward client-first development and opt in SSR features with strong type safety guarantees. While still evolving, it offers a compelling alternative for developers seeking more transparency, flexibility, and control.


As the React ecosystem continues to evolve, both frameworks will likely adapt and improve. For now, developers have two excellent options that cater to different architectural philosophies and project requirements.


The competition between these frameworks ultimately benefits the entire React community by driving innovation and pushing the boundaries of what's possible in modern web development.


Whether you choose TanStack Start or Next.js, you're selecting a powerful tool capable of building sophisticated web applications in 2025 and beyond. However, keep in mind that the TanStack Start is still in Beta.



References






 1.  https://tanstack.com/router/latest/docs/framework/react/guide/tanstack-start "TanStack Start is a full-stack framework for building server-rendered React applications built on top of TanStack Router." ↩︎ ↩︎
     

 2.  https://tanstack.com/start/latest/docs/framework/react/learn-the-basics "TanStack Start is (currently*) powered by Vinxi, Nitro and TanStack Router." ↩︎
     

 3.  https://tanstack.com/start/latest/docs/framework/react/overview "Tanstack start Overview" ↩︎ ↩︎ ↩︎ ↩︎
     

 4.  https://tanstack.com/router/latest/docs/framework/react/routing/virtual-file-routes "TanStack Router - Virtual File Routes" ↩︎
     

 5.  https://tanstack.com/router/latest/docs/framework/react/routing/code-based-routing "TanStack Router - Code-Based Routing" ↩︎
     

 6.  https://nextjs.org/docs/app/building-your-application/routing "Official documentation on the App Router architecture and routing system" ↩︎
     

 7.  https://nextjs.org/docs/app/building-your-application/rendering/server-components "Comprehensive guide to Server Components in Next.js" ↩︎
     

 8.  https://nextjs.org/docs/app/building-your-application/routing/linking-and-navigating#4-partial-rendering "Next.js 15 documentation on partial rendering" ↩︎
     

 9.  https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations "Server Actions and Mutations in Next.js 15" ↩︎
     

 10. https://nextjs.org/docs/app/building-your-application/optimizing/metadata "Metadata API in Next.js 15" ↩︎
     

 11. https://nextjs.org/blog/next-15#react-19 "Next.js 15 blog post on React 19 support" ↩︎
     

 12. https://nextjs.org/blog/turbopack-for-development-stable "Next.js 15 blog post on Turbopack for development" ↩︎
     

 13. https://nextjs.org/blog/next-15-3#turbopack-builds-alpha "Next.js 15 blog post on Turbopack builds" ↩︎
     

 14. https://tanstack.com/start/latest/docs/framework/react/learn-the-basics#routes "TanStack Start - Routes." ↩︎
     

 15. https://tanstack.com/start/latest/docs/framework/react/learn-the-basics "Details the transparent file structure with client.tsx, router.tsx, and ssr.tsx files" ↩︎
     

 16. https://nextjs.org/docs/app/getting-started/installation "Describes the automated setup process using create-next-app that sets up 'everything automatically for you'" ↩︎
     

 17. https://nextjs.org/docs/13 "Next.js 13 (stable) lays the foundations to be dynamic without limits: Easier, faster, less client JS." ↩︎
     

 18. https://nextjs.org/docs/app/getting-started/deploying "A managed platform is a practical option for deploying your Next.js app, as these providers take care of hosting, scaling, and server configuration for you." ↩︎
     

 19. https://nextjs.org/docs/pages/building-your-application/deploying#self-hosting "You can self-host Next.js with support for all features using Node.js or Docker. You can also do a Static HTML Export, which has some limitations." ↩︎
     

 20. https://tanstack.com/start/latest/docs/framework/react/quick-start "To quickly deploy an example, click the Deploy to Netlify button on an example's page to both clone and deploy the example to Netlify." ↩︎
     

 21. https://nitro.build/deploy "Nitro deployment guide" ↩︎
     



Development

TanStack Start vs Next.js: Choosing the Right React Framework in 2025

Add 3D to React: Intro to React-Three-Fiber

Tired of manually writing and maintaining API clients in React? Leverage Orval and TanstackQuery to generate API clients from OpenAPI/Swagger definitions.

Effortless API Clients: Create from OpenAPI with Orval & TanstackQuery

When creating a web application that interacts with an API, it is common to use a client library or write an API client manually that abstracts the API calls. This allows you to focus on the front end of your application without worrying about the details of the API like request headers, query parameters, and response handling. With that in mind, it is essential to keep the API client in sync with the API itself to avoid any inconsistencies or bugs.

What if you:

 * didn't have to write the API client manually and keep it in sync with the API?
 * get all the types, request parameters, response schemas, and API endpoints automatically?
 * generate the API client from the API definition itself?

This is where OpenAPI/Swagger definition and Orval comes into play.

In this blog, we will generate an API client from OpenAPI/Swagger definitions using Orval and TanstackQuery as our API client library of choice in a React (NextJS) application.

Orval is a tool that generates API clients from OpenAPI/Swagger definitions, and TanstackQuery is a library that provides a set of hooks and utilities for making API requests in React applications. It also provides a way to access the data as you would with some state management libraries like Redux or Recoil but without the boilerplate. Together, they provide a seamless way to generate and use API clients in your React applications without much effort.

Let's get started!


Setup

As stated earlier, we will be using Orval and OpenAPI/Swagger definitions that we receive from our API provider. For this blog, we will use the Petstore API as our example API. The Petstore API provides a simple REST API for managing pets. You can find the OpenAPI/Swagger definition for the Petstore API.

To generate the API client, we need to install Orval and create a configuration file that specifies the input OpenAPI/Swagger definition and the output directory for the generated API client.

The example configuration file looks like this:

// orval.config.ts
import { defineConfig } from 'orval';

const defaultQueryOverride = {
  useQuery: true,
  signal: true,
  useSuspenseQuery: true,
};

export default defineConfig({
  project_name: {
    input: {
      target: './src/api/openapi.json',
      filters: {
        // you can filter the tags you want/don't want to generate using regex
        // e.g. match all strings that don't contain healthcheck
        tags: [https://blog.prototyp.digital/^(?!.*healthcheck).*$/],
      },
    },
    output: {
      // clean the output directory before generating the API client
      clean: true,
      // splits the generated files by tags
      mode: 'tags-split',
      // output directory for the generated API client
      target: './openapi-config',
      // output directory for the generated API types
      schemas: './openapi-schemas',
      // default directory to append to target/schemas
      workspace: './src/',
      // generate barrel files for src directory and schemas directory
      indexFiles: true,
      // client library to use for the generated API client
      // supported libraries: angular, axios, axios-functions, react-query, svelte-query, vue-query, swr, zod
      client: 'react-query',
      prettier: true,
      // generate mock data for the API client
      mock: false,
      // sets the default query options for all queries to be optional, useful for Orval + TanstackQuery integration (more info in docs)
      allParamsOptional: true,
      override: {
        // default query options for all queries
        query: {
          useQuery: true,
          signal: true,
          useSuspenseQuery: true,
        },
        operations: {
          // override query options for specific operations
          ["operation_id"]: {
            query: {
              ...defaultQueryOverride,
              useInfinite: true,
              useInfiniteQueryParam: 'page',
            },
          },
          ...
        },
        mutator: {
          // default api client definition
          path: './custom-client.ts',
          name: 'customClient',
        },
      },
    },
  },
});



In the configuration file, we specify the input OpenAPI/Swagger definition file, the output directory for the generated API client, and the client library to use for the generated API client. We also specify the default query options for all queries and override them for specific operations if needed.

The custom client definition allows you to customize the generated API client by providing your own implementation for the API client. This is useful when you want to add custom logic, authentication to the generated API client or use a different client library.

Example of a custom client definition:

// custom-client.ts
import Axios, { AxiosError, AxiosHeaders, AxiosRequestConfig } from "axios";
import { getAuth, getIdToken, signOut } from "firebase/auth";

export const AXIOS_INSTANCE = Axios.create({
  baseURL: process.env.NEXT_PUBLIC_BACKEND_API,
}); // use your own URL here or environment variable

// add a second `options` argument here if you want to pass extra options to each generated query
export const customClient = async <T>(
  config: AxiosRequestConfig,
  options?: AxiosRequestConfig
): Promise<T> => {
  // example authentication using Firebase
  const auth = getAuth();
  const user = auth.currentUser;
  let token: undefined | string = undefined;

  const headers = new AxiosHeaders();

  if (user) {
    token = await getIdToken(user);
    headers.set("Authorization", `Bearer ${token}`);
  }

  const source = Axios.CancelToken.source();
  const promise = AXIOS_INSTANCE({
    ...config,
    ...options,
    cancelToken: source.token,
    headers: {
      ...config.headers,
      ...headers,
    },
  }).then(({ data }) => data);

  promise.cancel = () => {
    source.cancel("Query was cancelled");
  };

  return promise;
};

AXIOS_INSTANCE.interceptors.response.use(
  response => {
    return response;
  },
  error => {
    // example of handling 401 unauthorized error with Firebase
    if (error.response?.status === 401) {
      const auth = getAuth();
      signOut(auth);
    }
    return Promise.reject(error);
  }
);

// In some case with react-query and swr you want to be able to override the return error type so you can also do it here like this
export type ErrorType<Error> = AxiosError<Error>;

export type BodyType<BodyData> = BodyData;

In the custom client definition, we define a custom client function that takes an Axios request configuration and an optional options object as arguments and returns a promise that resolves to the response data. We also define an Axios instance with a base URL and an interceptor that handles 401 unauthorized errors by signing out the user using Firebase authentication but you can use any other authentication method.

Now that we have our configuration file and custom client definition ready, we can generate the API client using Orval. To do this, we need to install Orval and run the following command:

curl https://petstore.swagger.io/v2/swagger.json > ./src/api/openapi.json && npx orval --config ./src/api/orval.config.ts && npx prettier --write ./src/api/ && rm ./apps/fe/modules/api/openapi.json

This command downloads the OpenAPI/Swagger definition for the Petstore API, generates the API client using Orval, formats the generated files using Prettier, and removes the downloaded OpenAPI/Swagger definition file. You can add this command to your package.json scripts for easy access.

After running the command, you should see the generated API client in the output directory specified in the configuration file. The generated API client contains all the types, request parameters, response schemas, and API endpoints defined in the OpenAPI/Swagger definition.

Example of the generated folder structure and API client using Orval and TanstackQuery

Each API endpoint is represented as a hook that you can use in your React components to make API requests. The generated API client also provides a set of utilities for handling loading, error, and data states for each API request.

Now that we have the generated API client, we can use it in our React application to interact with the Petstore API.


Using the API client in a React application

To use the generated API client in a React application we can just import the generated hooks and use them in our components. Here is an example of how to use the generated API client in a React component:


Fetching the data (Query)

// components/Pets.tsx
import { useGetPets } from "../openapi-config/pets";
import { Pets as PetsType } from "../openapi-schemas/pets";

const Pets = () => {
  const { data, error, isLoading } = useGetPets();

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <div>
      <h1>Pets</h1>
      <ul>
        {data?.map((pet: PetsType) => (
          <li key={pet.id}>{pet.name}</li>
        ))}
      </ul>
    </div>
  );
};

export default Pets;




Creating a new pet (Mutation)

// components/CreatePet.tsx
import { useCreatePet } from "../openapi-config/pets";
import { Pet as PetType } from "../openapi-schemas/pets";

const CreatePet = () => {
  const { mutate, isPending, error } = useCreatePet({
    mutation: {
      mutationKey: "create",
      onSuccess: () => {
        alert("Pet created successfully!");
        // redirect to the pets page and invalidate the query cache
      },
    },
    request: {
      headers: {
        "Content-Type": "application/json",
      },
    },
  });

  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const pet: PetType = {
      name: formData.get("name") as string,
      tag: formData.get("tag") as string,
    };

    await mutate(pet);
  };

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (error) {
    return <div>Error: {error.message}</div>;
  }

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Name:
        <input type="text" name="name" />
      </label>
      <label>
        Tag:
        <input type="text" name="tag" />
      </label>
      <button type="submit">Create Pet</button>
    </form>
  );
};

export default CreatePet;



In the example above, we import the generated hooks for fetching pets and creating a new pet from the generated API client. We use the useGetPets hook to fetch the list of pets and display them in a list. We use the useCreatePet hook to create a new pet by submitting a form with the pet's name and tag.

The generated hooks handle loading, error, and data states for each API request, making it easy to interact with the API in a React application. You can also customize the request headers, query parameters, and response handling using the options object passed to the hooks.

This leaves us with a clean and maintainable way to interact with the API in our React application without worrying about the details of the API and changes in the API definition over time since we can easily regenerate the API client anytime the API definition changes.


Why not use OpenAPI/Swagger Codegen?

In this blog, we learned how to generate an API client from OpenAPI/Swagger definitions using Orval and TanstackQuery in a React application. We saw how to create a configuration file for Orval, generate the API client, and use the generated API client in a React component to interact with the Petstore API.

The more complex your API becomes, the more beneficial it is to generate the API client from the API definition to avoid inconsistencies and bugs. Orval and TanstackQuery provide a seamless way to generate and use API clients in your React applications without much effort, allowing you to focus on the front end of your application as well as keeping type safety and consistency in your API client.



If you have any questions or feedback, feel free to reach out to us or check out the our other blogs on prototyp.digital.blog.

AuthorJosip Papež

Start a Project