Przejdź do głównej zawartości

Codegen i odczyty cacheowane na brzegu

doswiftly codegen init konfiguruje codegen dla Twojego storefronta jedną komendą — generuje typy z operacji GraphQL i przygotowuje projekt pod odczyty cacheowane na brzegu. Ten przewodnik wyjaśnia, po co to robić, jak to ustawić i jak pisać operacje, żeby skorzystać z cache.

Po co to​

Publiczne zapytania odczytujące dane (lista produktów, kategoria, szczegóły produktu) mogą być cacheowane na brzegu — blisko kupującego, zanim żądanie dotrze do API — pod warunkiem, że storefront wysyła je jako krótki identyfikator zamiast pełnej treści zapytania. Ten identyfikator to documentId, a mechanizm nazywa się dokumentami utrwalonymi (persisted documents, znanymi też jako trusted documents).

Działa to tak: codegen liczy stabilny documentId dla każdej operacji w Twoim kodzie i buduje manifest — mapę documentId → zapytanie. Przy wdrożeniu manifest trafia do API. W czasie działania storefront wysyła już tylko documentId; API rozpoznaje zapytanie po identyfikatorze, a krótkie, powtarzalne żądania publicznych odczytów mogą zostać obsłużone z cache na brzegu.

Bez tej konfiguracji storefront nadal działa — zapytania po prostu lecą pełną treścią (cała operacja w każdym żądaniu). Tracisz tylko możliwość cache na brzegu dla publicznych odczytów.

Co podlega cache, a co nie

Cacheowane na brzegu mogą być wyłącznie publiczne odczyty (katalog, treści). Operacje wymagające zalogowania (koszyk, konto, zamówienia) oraz wszystkie mutacje zawsze trafiają do API i nie są cacheowane. Wybór strategii renderowania i okien świeżości opisuje Strategia renderowania.

Setup jedną komendą​

W katalogu projektu uruchom:

doswiftly codegen init

Komenda:

  • tworzy plik codegen.ts z gotową konfiguracją opartą o @doswiftly/storefront-operations/codegen (schemat i format documentId są już poprawnie podpięte),
  • dodaje wymagane zależności deweloperskie w zweryfikowanych wersjach: @graphql-codegen/cli@^7, @graphql-codegen/client-preset@^4 oraz graphql@^16 (i ostrzega, jeśli projekt ma już niezgodną wersję graphql),
  • dodaje skrypt codegen do package.json.

Komenda jest idempotentna — jeśli codegen.ts już istnieje, nie nadpisze go (możesz uruchamiać ją bez obaw).

Wygenerowany codegen.ts jest minimalny:

import { createCodegenConfig } from '@doswiftly/storefront-operations/codegen';

// `documents` wskazuje pliki, w których piszesz operacje GraphQL.
export default createCodegenConfig({ documents: 'src/**/*.{ts,tsx}' });

Jeśli wolisz dodać zależności ręcznie (np. w istniejącym projekcie), użyj przypiętych wersji — client-preset nie wspiera jeszcze graphql v17 (operacje z fragmentami nie wygenerują się):

pnpm add -D @graphql-codegen/cli@^7 @graphql-codegen/client-preset@^4 graphql@^16

Po konfiguracji wygeneruj kod raz, żeby powstał katalog src/gql/:

pnpm codegen

Jak pisać operacje​

Operacje pisz przez funkcję graphql() z wygenerowanego katalogu src/gql/ — nie jako zwykłe stringi. Tylko operacje przepuszczone przez graphql() trafiają do manifestu i niosą documentId w zbudowanym kodzie:

import { graphql } from '@/gql';

const ProductsQuery = graphql(`
  query Products {
    products(first: 12) {
      nodes {
        id
        title
      }
    }
  }
`);

ProductsQuery jest w pełni otypowany (zmienne i kształt odpowiedzi) i niesie swój documentId. Przekaż go do klienta SDK tak samo, jak każdą inną operację.

Zwykły string omija cache

Zapytanie zapisane jako zwykły string (poza graphql()) nadal zadziała, ale nie dostanie documentId — poleci pełną treścią i nie skorzysta z cache na brzegu. Jeśli zależy Ci na cache publicznych odczytów, pisz je przez graphql().

Codegen odpala CLI, nie Ty​

Nie wpinaj codegenu we własny skrypt build. Uruchamia go za Ciebie CLI we właściwym momencie:

  • doswiftly dev uruchamia codegen w trybie watch — pliki w src/gql/ regenerują się automatycznie, gdy edytujesz operacje.
  • doswiftly deploy uruchamia codegen raz, a zaraz potem — zanim ruszy build — publikuje manifest (documentId → zapytanie) do API. Jeśli publikacja się nie powiedzie, deploy przerywa się od razu (błąd fatalny), zamiast dopiero w trakcie budowania stron.
Nie uruchamiaj codegenu podwójnie

Jeśli dodatkowo wpniesz codegen do skryptu build, codegen uruchomi się dwa razy (raz z CLI, raz z buildu). Zostaw uruchamianie codegenu CLI — skrypt codegen w package.json służy do ręcznego, jednorazowego wygenerowania kodu, nie do wpinania w build.

Świeżość w trybie deweloperskim​

W trybie doswiftly dev Twoje zapytania i tak lecą pełną treścią — manifest jest publikowany dopiero przy doswiftly deploy, więc cache na brzegu zaczyna działać dopiero po wdrożeniu. To normalne; lokalnie pracujesz na świeżych danych, bez warstwy cache.

Następne kroki​