Replacing Server Actions in Next.js: A Deep Dive into TanStack Query

When working on my Next.js application, I initially relied on server actions for data fetching and updates. While server actions provide a great way to handle server-side logic, I started looking for alternatives that offer more flexibility, especially when dealing with client-side state and caching. That’s when I came across TanStack Query.

TanStack Query is designed to manage server-state efficiently, offering features like caching, background synchronization, and automatic retries. It simplifies data fetching while improving application performance, making it a compelling alternative to server actions.

Why Consider TanStack Query for Next.js?

In Next.js, server actions are useful for handling server-side logic without setting up API routes. However, for cases where real-time updates, client-side caching, or background data synchronization are needed, server actions might not be the best fit. This is where TanStack Query stands out:

• Automatic caching reduces redundant API calls.

• Background refetching ensures data is always up to date.

• Optimistic updates improve perceived performance.

• Less manual state management, unlike using useState or useEffect.

How TanStack Query Works Under the Hood

TanStack Query follows a predictable lifecycle for managing server-state efficiently:

1. Query Execution and Caching

   • When you call useQuery, TanStack Query first checks if the requested data is already cached.

   • If cached data exists and is fresh, it returns the cached data instantly without hitting the API.

   • If no cache exists or the data is stale, it fetches fresh data from the server.

2. Stale-While-Revalidate Mechanism

   • Data retrieved from cache is marked as stale after a certain period.

   • When stale data is accessed, a background fetch is triggered while still serving the old data to avoid UI flickers.

   • Once new data is available, it updates the UI automatically.

3. Garbage Collection

   • Cached data that hasn’t been accessed for a while is automatically removed to free up memory.

   • The default cache time is 5 minutes, but it can be adjusted using query options.

4. Automatic Background Refetching

   • Whenever a user re-focuses the page or regains an internet connection, TanStack Query refetches data automatically.

   • This ensures data remains fresh even when the user returns to an inactive tab.

5. Invalidation & Query Dependencies

   • When data is modified using useMutation, related queries are invalidated to trigger a refetch.

   • This ensures consistency between the client-side state and the backend.

These features make TanStack Query extremely powerful for managing server-state efficiently in Next.js applications.

Setting Up TanStack Query in a Next.js App

To get started, install the library:

npm install @tanstack/react-query

Then, wrap your application with the QueryClientProvider in _app.tsx (if using the App Router, wrap it in layout.tsx).

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function MyApp({ Component, pageProps }) {
  return (
    <QueryClientProvider client={queryClient}>
      <Component {...pageProps} />
    </QueryClientProvider>
  );
}

Now, queries can be used inside components to fetch data.

Fetching Data with useQuery in Next.js

Using useQuery, you can fetch data and handle states efficiently:

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

const fetchUsers = async () => {
  const { data } = await axios.get('/api/users');
  return data;
};

function UsersList() {
  const { data, isLoading, error } = useQuery(['users'], fetchUsers);

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

This approach avoids manually handling loading states or refetching data on interactions.

Mutating Data with useMutation

For creating, updating, or deleting data, useMutation helps manage requests efficiently:

import { useMutation, useQueryClient } from '@tanstack/react-query';
import axios from 'axios';

const addUser = async (user) => {
  const { data } = await axios.post('/api/users', user);
  return data;
};

function AddUserButton() {
  const queryClient = useQueryClient();
  const mutation = useMutation(addUser, {
    onSuccess: () => {
      queryClient.invalidateQueries(['users']);
    },
  });

  return (
    <button onClick={() => mutation.mutate({ name: 'New User' })}>
      Add User
    </button>
  );
}

This ensures the UI updates without requiring a full page reload.

Optimizing Next.js Applications with TanStack Query

1. Improved Performance

By caching data, fewer API calls are made, reducing server load.

2. Better User Experience

Instant loading states and background data refetching keep the UI responsive.

3. Efficient Data Synchronization

With real-time updates and revalidation, applications stay up to date without excessive API requests.

4. Simplifies Code

It removes the need for useState, useEffect, and manual fetch handling.

When to Use TanStack Query in Next.js?

• Fetching and caching API data efficiently.

• Keeping UI updated with real-time or background sync.

• Handling complex async operations like pagination and optimistic updates.

When Not to Use It?

• For managing UI state (e.g., modals, toggles).

• If all API calls are strictly server-side and don’t require client caching.

Final Thoughts

After exploring TanStack Query, it became clear that for certain use cases, it provides significant advantages over server actions in Next.js. While server actions are great for handling direct server interactions, TanStack Query shines when efficient client-side data management is needed.

For projects that require real-time updates, caching, and a smooth user experience, integrating TanStack Query is a solid choice.

Next Steps

• Explore the TanStack Query Docs for advanced features.

• Try replacing server actions with TanStack Query in a Next.js project and see the improvements.
  

- Jagadhiswaran devaraj