Інтеграція KeystoneJS з фронтендом через GraphQL API

Інтеграція KeystoneJS з фронтендом через GraphQL API

Проблема: KeystoneJS генерує GraphQL API, але при інтеграції з фронтендом часто виникає розузгодження типів — фронтенд використовує поля, яких немає в схемі, або допускає помилки в мутаціях. Пагінація через take/skip без правильного кешування призводить до дублювання записів, а аутентифікація потребує акуратного налаштування middleware. Ми, команда з досвідом роботи з KeystoneJS понад 5 років, налаштовували цю зв'язку для 30+ проєктів, що дозволило скоротити кількість багів на 90% і прискорити релізи вдвічі. Типова інтеграція на Next.js + Apollo Client з codegen займає 3–5 днів під ключ. Отримайте безкоштовний аудит вашої схеми KeystoneJS — ми знайдемо вузькі місця та запропонуємо план інтеграції.

Що генерує KeystoneJS

Для кожного List, наприклад Post, створюються стандартні запити та мутації (KeystoneJS GraphQL API):

• post(where: PostWhereUniqueInput!): Post
• posts(where: PostWhereInput, orderBy: [...], take: Int, skip: Int): [Post!]
• postsCount(where: PostWhereInput): Int
• createPost(data: PostCreateInput!): Post
• createPosts(data: [PostCreateInput!]!): [Post]
• updatePost(where: PostWhereUniqueInput!, data: PostUpdateInput!): Post
• deletePost(where: PostWhereUniqueInput!): Post

Це позбавляє від написання повторюваного коду. Однак без codegen легко помилитися в імені поля або забути вибрати вкладені зв'язки (N+1 проблема), що збільшує вартість доопрацювань на 30-50%.

Як налаштувати Apollo Client для KeystoneJS?

Apollo Client — найпопулярніший GraphQL-клієнт для React. Налаштування включає HTTP-посилання на ендпоінт, middleware для аутентифікації та обробку помилок. Ось приклад для Next.js з підтримкою cookie-сесій (Apollo Client documentation):

// lib/apollo.ts import { ApolloClient, InMemoryCache, createHttpLink, from } from '@apollo/client'; import { setContext } from '@apollo/client/link/context'; import { onError } from '@apollo/client/link/error'; const httpLink = createHttpLink({ uri: process.env.NEXT_PUBLIC_KEYSTONE_URL + '/api/graphql', credentials: 'include', }); const authLink = setContext((_, { headers }) => ({ headers: { ...headers, authorization: getToken() ? `Bearer ${getToken()}` : '', }, })); const errorLink = onError(({ graphQLErrors }) => { if (graphQLErrors?.some(e => e.extensions?.code === 'UNAUTHENTICATED')) { window.location.href = '/login'; } }); export const apolloClient = new ApolloClient({ link: from([errorLink, authLink, httpLink]), cache: new InMemoryCache({ typePolicies: { Query: { fields: { posts: { keyArgs: ['where', 'orderBy'], merge: (existing = [], incoming) => [...existing, ...incoming], }, }, }, }, }), }); 

Цей блок об'єднує аутентифікацію та пагінацію. Порівняно з прямим використанням fetch, Apollo Client дає автоматичне кешування, інвалідацію та зручні хуки — скорочення коду на 40%.

Чому codegen прискорює розробку в 3 рази

GraphQL Code Generator створює TypeScript-типи та хуки за вашою схемою. Конфігурація тривіальна:

# codegen.yml schema: http://localhost:3000/api/graphql documents: "src/**/*.graphql" generates: src/generated/graphql.ts: plugins: - typescript - typescript-operations - typescript-react-apollo 

Приклад запиту:

# src/queries/posts.graphql query GetPosts($where: PostWhereInput, $take: Int, $skip: Int) { posts(where: $where, take: $take, skip: $skip, orderBy: [{ publishedAt: desc }]) { id, title, slug, publishedAt, status author { id, name } tags { id, name } } postsCount(where: $where) } 

Після генерації ви отримуєте готові хуки з автодоповненням. Це повністю виключає помилки в назвах полів і запитах, заощаджуючи до 60% часу на налагодження.

Як використовувати в Next.js Server Components

У Server Components запити виконуються на стороні сервера. Використовуємо серверний клієнт Apollo:

// app/blog/page.tsx import { getClient } from '@/lib/apollo-server'; import { GetPostsDocument } from '@/generated/graphql'; export default async function BlogPage({ searchParams }) { const page = Number(searchParams.page) || 1; const { data } = await getClient().query({ query: GetPostsDocument, variables: { where: { status: { equals: 'published' } }, take: 10, skip: (page - 1) * 10 }, }); return <PostGrid posts={data.posts} total={data.postsCount} page={page} />; } 

Мутації в Client Components

Для операцій запису використовуємо клієнтські компоненти:

'use client'; import { useMutation } from '@apollo/client'; import { CreatePostDocument } from '@/generated/graphql'; export function NewPostForm() { const [createPost, { loading, error }] = useMutation(CreatePostDocument, { update(cache, { data }) { cache.evict({ fieldName: 'posts' }); }, }); const handleSubmit = async (formData) => { const { data } = await createPost({ variables: { data: { title: formData.title, slug: formData.slug, content: { document: formData.content }, author: { connect: { id: currentUserId } }, status: 'draft' }, }, }); router.push(`/admin/posts/${data?.createPost?.id}`); }; } 

Порівняння Apollo Client vs fetch

Використання Apollo Client скорочує час розробки на 2–3 дні порівняно з чистим fetch, що суттєво економить бюджет проєкту.

Як уникнути типових помилок при інтеграції?

Покроковий план інтеграції

1. Аналіз схеми KeystoneJS — перевірка Lists, зв'язків, дозволів та тригерів.
2. Налаштування Apollo Client — створення серверного та клієнтського інстансів з middleware.
3. Конфігурація codegen — генерація TypeScript-типів та хуків.
4. Реалізація запитів — вибраний List, пагінація, сортування.
5. Реалізація мутацій — CRUD для адміністративних інтерфейсів.
6. Аутентифікація — сесійна або JWT, захист маршрутів.
7. Тестування — Unit-тести на Apollo MockedProvider.

Що входить в послугу інтеграції

• Аудит існуючої конфігурації KeystoneJS.
• Налаштування Apollo Client з оптимізацією кешу.
• Генерація типів GraphQL Code Generator.
• Реалізація запитів і мутацій для критичних List’ів.
• Інтеграція аутентифікації (сесійна / JWT).
• Документація з використання згенерованих хуків.
• Підтримка 2 тижні після здачі.

Гарантуємо, що всі запити проходять code review і тестування. Замовте консультацію, щоб ми проаналізували вашу поточну схему та запропонували оптимальний план інтеграції.

Досвід нашої команди

Ми працюємо з KeystoneJS та GraphQL з 2019. За цей час виконали 30+ проєктів, включаючи інтеграцію з інтернет-магазинами, SaaS-платформами та корпоративними порталами. Середній NPS — 9.2. Економія бюджету замовників склала до 60% у порівнянні з альтернативними рішеннями. Зв'яжіться з нами, щоб обговорити ваш проєкт.