TanStack Query у Next.js · fullstack.org.ua

Просунутий21 хв· Fullstack Team

TanStack Query у Next.js

Підключите TanStack Query для кешування, синхронізації, повторних запитів і мутацій у Next.js.

Навіщо потрібен TanStack Query

TanStack Query керує серверним станом у React-застосунку:

кешує результати запитів;
не повторює однакові запити без потреби;
автоматично оновлює застарілі дані;
повторює невдалі запити;
відстежує стани loading, error і success;
підтримує мутації та інвалідацію кешу;
інтегрується із серверним рендерингом і гідрацією в Next.js.

TanStack Query не замінює useState для локального стану інтерфейсу. Його основне завдання — зберігати та синхронізувати дані, які надходять із сервера.

Встановлення

bash

npm install @tanstack/react-query

tsx

'use client';

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

type Props = {
  children: React.ReactNode;
};

export function Providers({ children }: Props) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 30_000,
            gcTime: 5 * 60_000,
            retry: 2,
            refetchOnWindowFocus: true,
            refetchOnReconnect: true,
          },
          mutations: {
            retry: 0,
          },
        },
      }),
  );

  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

tsx

import type { Metadata } from 'next';
import { Providers } from './providers';

export const metadata: Metadata = {
  title: 'TanStack Query Demo',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="uk">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

typescript

export type Post = {
  id: string;
  title: string;
  body: string;
  createdAt: string;
};

let posts: Post[] = [
  {
    id: '1',
    title: 'Перший допис',
    body: 'Вміст першого допису',
    createdAt: new Date().toISOString(),
  },
  {
    id: '2',
    title: 'Другий допис',
    body: 'Вміст другого допису',
    createdAt: new Date().toISOString(),
  },
];

export async function getPosts(): Promise<Post[]> {
  return posts;
}

export async function createPost(input: {
  title: string;
  body: string;
}): Promise<Post> {
  const post: Post = {
    id: crypto.randomUUID(),
    title: input.title,
    body: input.body,
    createdAt: new Date().toISOString(),
  };

  posts = [post, ...posts];

  return post;
}

typescript

import { createPost, getPosts } from '@/lib/posts';

export async function GET() {
  const posts = await getPosts();

  return Response.json(posts);
}

export async function POST(request: Request) {
  const body = (await request.json()) as {
    title?: string;
    body?: string;
  };

  if (!body.title?.trim() || !body.body?.trim()) {
    return Response.json(
      { message: 'Заголовок і текст є обов’язковими' },
      { status: 400 },
    );
  }

  const post = await createPost({
    title: body.title.trim(),
    body: body.body.trim(),
  });

  return Response.json(post, { status: 201 });
}

tsx

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query';
import { getPosts } from '@/lib/posts';
import { PostsList } from './posts-list';

export default async function PostsPage() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30_000,
      },
    },
  });

  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <main>
        <h1>Дописи</h1>
        <PostsList />
      </main>
    </HydrationBoundary>
  );
}

tsx

'use client';

import { useQuery } from '@tanstack/react-query';
import type { Post } from '@/lib/posts';

async function fetchPosts({
  signal,
}: {
  signal: AbortSignal;
}): Promise<Post[]> {
  const response = await fetch('/api/posts', {
    signal,
    cache: 'no-store',
  });

  if (!response.ok) {
    throw new Error('Не вдалося завантажити дописи');
  }

  return response.json();
}

export function PostsList() {
  const postsQuery = useQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  });

  if (postsQuery.isPending) {
    return <p>Завантаження...</p>;
  }

  if (postsQuery.isError) {
    return (
      <div>
        <p>Помилка: {postsQuery.error.message}</p>
        <button type="button" onClick={() => postsQuery.refetch()}>
          Спробувати ще раз
        </button>
      </div>
    );
  }

  return (
    <section>
      <p>
        Стан кешу:{' '}
        {postsQuery.isFetching ? 'оновлення...' : 'актуальний'}
      </p>

      <ul>
        {postsQuery.data.map((post) => (
          <li key={post.id}>
            <h2>{post.title}</h2>
            <p>{post.body}</p>
          </li>
        ))}
      </ul>
    </section>
  );
}

tsx

const query = useQuery({
  queryKey: ['posts'],
  queryFn: fetchPosts,
  retry: (failureCount, error) => {
    if (error instanceof Error && error.message.includes('401')) {
      return false;
    }

    return failureCount < 2;
  },
});

tsx

'use client';

import { FormEvent, useState } from 'react';
import {
  useMutation,
  useQueryClient,
} from '@tanstack/react-query';
import type { Post } from '@/lib/posts';

type CreatePostInput = {
  title: string;
  body: string;
};

async function createPost(input: CreatePostInput): Promise<Post> {
  const response = await fetch('/api/posts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  });

  if (!response.ok) {
    const error = (await response.json()) as { message?: string };

    throw new Error(error.message ?? 'Не вдалося створити допис');
  }

  return response.json();
}

export function CreatePostForm() {
  const queryClient = useQueryClient();
  const [title, setTitle] = useState('');
  const [body, setBody] = useState('');

  const mutation = useMutation({
    mutationFn: createPost,
    onSuccess: async () => {
      await queryClient.invalidateQueries({
        queryKey: ['posts'],
      });

      setTitle('');
      setBody('');
    },
  });

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();

    mutation.mutate({
      title,
      body,
    });
  }

  return (
    <form onSubmit={handleSubmit}>
      <label>
        Заголовок
        <input
          value={title}
          onChange={(event) => setTitle(event.target.value)}
          disabled={mutation.isPending}
        />
      </label>

      <label>
        Текст
        <textarea
          value={body}
          onChange={(event) => setBody(event.target.value)}
          disabled={mutation.isPending}
        />
      </label>

      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? 'Збереження...' : 'Створити'}
      </button>

      {mutation.isError && (
        <p role="alert">{mutation.error.message}</p>
      )}

      {mutation.isSuccess && <p>Допис створено</p>}
    </form>
  );
}

tsx

import {
  dehydrate,
  HydrationBoundary,
  QueryClient,
} from '@tanstack/react-query';
import { getPosts } from '@/lib/posts';
import { CreatePostForm } from './create-post-form';
import { PostsList } from './posts-list';

export default async function PostsPage() {
  const queryClient = new QueryClient();

  await queryClient.prefetchQuery({
    queryKey: ['posts'],
    queryFn: getPosts,
  });

  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <main>
        <h1>Дописи</h1>
        <CreatePostForm />
        <PostsList />
      </main>
    </HydrationBoundary>
  );
}

tsx

const mutation = useMutation({
  mutationFn: createPost,

  onSuccess: (createdPost) => {
    queryClient.setQueryData<Post[]>(
      ['posts'],
      (currentPosts = []) => [createdPost, ...currentPosts],
    );
  },
});

TanStack Query у Next.js

Навіщо потрібен TanStack Query

Встановлення

Налаштування QueryClient

Чому використовується `useState`

Модель даних і API Route Handler

Запит і ключ кешу

Кешування та застарілість

`staleTime`

`gcTime`

Важлива різниця

Серверне попереднє завантаження і гідрація

Читання даних у клієнтському компоненті

Сигнал скасування

Повторні запити

Автоматична синхронізація

Мутації

Інвалідація кешу

Оновлення кешу без повторного запиту

Ключі для параметризованих запитів

Розділення станів `isPending` та `isFetching`

Взаємодія з кешем Next.js

Поширені помилки

Створення `QueryClient` під час кожного рендеру

Використання хука в серверному компоненті

Відсутність параметрів у `queryKey`

Інвалідація неправильного ключа

Відсутність перевірки `response.ok`

Повторні мутації без контролю

Глобальний серверний `QueryClient`

Підсумок

TanStack Query у Next.js

Навіщо потрібен TanStack Query

Встановлення

Налаштування QueryClient

Чому використовується useState

Модель даних і API Route Handler

Запит і ключ кешу

Кешування та застарілість

staleTime

gcTime

Важлива різниця

Серверне попереднє завантаження і гідрація

Читання даних у клієнтському компоненті

Сигнал скасування

Повторні запити

Автоматична синхронізація

Мутації

Інвалідація кешу

Оновлення кешу без повторного запиту

Ключі для параметризованих запитів

Розділення станів isPending та isFetching

Взаємодія з кешем Next.js

Поширені помилки

Створення QueryClient під час кожного рендеру

Використання хука в серверному компоненті

Відсутність параметрів у queryKey

Інвалідація неправильного ключа

Відсутність перевірки response.ok

Повторні мутації без контролю

Глобальний серверний QueryClient

Підсумок

Чому використовується `useState`

`staleTime`

`gcTime`

Розділення станів `isPending` та `isFetching`

Створення `QueryClient` під час кожного рендеру

Відсутність параметрів у `queryKey`

Відсутність перевірки `response.ok`

Глобальний серверний `QueryClient`