Headless Starter Kit: kompletny przewodnik

Ten przewodnik obejmuje instalację, konfigurację i pełne wykorzystanie Headless Starter Kit: wtyczki WordPressa, która zamienia Twój sklep WooCommerce w commerce headless, wraz z gotowym starterem Next.js 15.

Przegląd

Headless Starter Kit składa się z dwóch elementów dostarczanych w ramach jednego zakupu:

1. Wtyczka WordPressa (ZIP do wgrania w /wp-admin/plugins.php), która udostępnia po stronie backendu: uwierzytelnianie JWT, API koszyka, most checkoutu, publiczny endpoint konfiguracji, webhooki ISR i ścisłe CORS.
2. Starter Next.js 15 (ZIP do pobrania z administracji WordPressa po włączeniu i skonfigurowaniu wtyczki), zawierający kompletny projekt Next.js ze stronami home, listingiem, kartą produktu w ISR, koszykiem, checkoutem, logowaniem, rejestracją i panelem klienta, ze zmiennymi środowiskowymi już wypełnionymi Twoimi adresami i sekretami.

Architektura jest celowo prosta: Twój WooCommerce pozostaje źródłem prawdy (produkty, zamówienia, stany magazynowe, płatności), a Next.js konsumuje REST API przez zabezpieczone trasy proxy. Bez duplikowania bazy danych, bez replikacji do ogarnięcia.

Wymagania

Po stronie WordPressa

• WordPress 6.4 lub nowszy
• WooCommerce 8.0 lub nowszy (testowane do 9.5)
• PHP 8.1 lub nowszy
• Bezpośrednie odnośniki ustawione na Nazwa wpisu (nie na Prosty)
• Aktywne HTTPS (niezbędne dla ciasteczek httpOnly i uwierzytelniania na produkcji)
• Para kluczy WooCommerce REST do odczytu i zapisu (generowane w WooCommerce → Ustawienia → Zaawansowane → REST API)

Po stronie frontendu Next.js

• Node.js 20 lub nowszy (zalecane: zarządzanie wersjami przez nvm)
• Hosting zgodny z Node: Vercel, VPS Hetzner, Netlify, Railway albo dowolny serwer uruchamiający Node 20+

Instalacja wtyczki WordPressa

1. W zapleczu WordPressa przejdź do Wtyczki → Dodaj nową wtyczkę → Wyślij wtyczkę na serwer.
2. Wybierz plik dfheadlessstarterkit.zip i kliknij Zainstaluj teraz.
3. Kliknij Włącz wtyczkę.
4. W lewym pasku bocznym pojawia się nowe menu Headless Kit z trzema zakładkami: Ustawienia, Diagnostyka, Pobierz starter.

Przy aktywacji wtyczka automatycznie generuje losowy sekret JWT i token rewalidacji. Możesz je w każdej chwili wygenerować od nowa w ustawieniach.

Konfiguracja

Otwórz Headless Kit → Ustawienia. Każda sekcja jest niezależna i można ją zmienić bez restartowania czegokolwiek.

Adres frontendu

Wpisz pełny publiczny adres swojej aplikacji Next.js, bez końcowego ukośnika. Przykład:

https://sklep.przyklad.pl

Ten adres służy trzem rzeczom: budowaniu webhooków ISR, zasilaniu zmiennej NEXT_PUBLIC_SITE_URL w dostarczonym starterze oraz domyślnej walidacji origin dla CORS.

Sekret JWT i token rewalidacji

Używane są dwa sekrety:

• Sekret JWT: podpisuje tokeny dostępu i odświeżania. Minimum 32 znaki. Nigdy go nie udostępniaj.
• Token rewalidacji: wysyłany w nagłówku Authorization: Bearer … webhooków ISR. Musi być identyczny ze zmienną REVALIDATE_TOKEN po stronie Next.js.

Przycisk Wygeneruj ponownie obok każdego pola tworzy losowy, kryptograficznie mocny sekret przez crypto.getRandomValues.

Tryb koszyka: JWT czy serwerowy?

Wybór odbywa się przez przycisk radiowy w ustawieniach.

Tryb JWT (domyślny, zalecany)

Cały koszyk serializowany jest w tokenie podpisanym HS256 i zwracany przez nagłówek X-DFHSK-Cart. Żadne dane nie są przechowywane po stronie WordPressa. Idealne przy:

• Wdrożeniach na Vercel edge, Cloudflare albo w wielu instancjach
• Sklepach o dużym ruchu, gdzie uniknięcie bazy danych przy każdym wywołaniu daje realny zysk
• Konfiguracjach, w których WordPress jest czystym API i nie potrzebuje sesji

Tryb serwerowy (WC_Session)

Koszyk żyje w natywnej tabeli WC_Session WooCommerce. Wybierz go, jeśli:

• Używasz rozszerzeń WooCommerce podpinających się pod koszyk (WooCommerce Subscriptions, Dynamic Pricing, wtyczki YITH i podobne)
• Chcesz zachować natywną logikę sesji WooCommerce (natywne przypomnienia o porzuconych koszykach, cross-sell po stronie serwera i pozostałe)

Origins dla CORS

Ścisła biała lista origins uprawnionych do wywoływania API. Jeden origin na wiersz, pełny format https://…. Obsługiwane są symbole wieloznaczne w subdomenach:

https://sklep.przyklad.pl
https://preview.przyklad.pl
https://*.previews.przyklad.pl
http://localhost:3000

Zdarzenia ISR

Pięć pól wyboru wskazuje, które zdarzenia WordPressa wyzwalają webhook ISR do Next.js:

• Produkty: save_post_product, woocommerce_update_product
• Kategorie: tworzenie, aktualizacja, usuwanie terminów taksonomii product_cat
• Zamówienia: zmiany statusu (przydatne do odświeżania strony konta klienta)
• Strony: save_post_page
• Kupony: tworzenie i aktualizacja kodów promocyjnych

Pole tekstowe Ścieżki do rewalidacji pozwala precyzyjnie określić, które ścieżki Next.js są rewalidowane przy każdym zdarzeniu (domyślnie wtyczka inteligentnie wyprowadza właściwe ścieżki).

Diagnostyka

Zakładka Headless Kit → Diagnostyka. Przy każdym wyświetleniu strony wykonywanych jest jedenaście automatycznych kontroli:

1. WooCommerce aktywne: klasa WooCommerce jest dostępna
2. Czyste bezpośrednie odnośniki: struktura nie jest ustawiona na Prosty
3. REST API osiągalne: /wp-json/ odpowiada kodem 200
4. HTTPS aktywne: is_ssl() zwraca true
5. Wykryty WPGraphQL: tylko informacja, nieblokująca
6. Sekret JWT ustawiony: minimum 32 znaki
7. Adres frontendu skonfigurowany: niepusty i w prawidłowym formacie URL
8. Origins CORS uzupełnione: co najmniej jeden origin
9. Token rewalidacji ustawiony: minimum 24 znaki
10. Klucze WooCommerce REST: wtyczka wykrywa aktywną parę consumer_key i consumer_secret
11. Tryb koszyka czytelny: wybrane przechowywanie działa

Każda kontrola wyświetla się na zielono (OK), pomarańczowo (ostrzeżenie, nieblokujące) albo czerwono (blokujące). Przed wdrożeniem na produkcję rozwiąż wszystko, co jest czerwone.

Pobranie i uruchomienie startera Next.js

Gdy ustawienia są wypełnione, a diagnostyka na zielono, otwórz Headless Kit → Pobierz starter. Kliknij duży przycisk Pobierz starter Next.js.

Dostarczany ZIP to kompletny projekt Next.js 15, generowany w locie z już wstrzykniętymi Twoimi adresami i sekretami. Podstawiane przy generowaniu placeholdery:

• {{SITE_URL}} → adres Twojego WordPressa
• {{FRONTEND_URL}} → skonfigurowany adres frontendu
• {{REVALIDATE_TOKEN}} → Twój token rewalidacji
• {{CURRENCY}} → waluta WooCommerce
• {{SITE_NAME}} → tytuł witryny
• {{LOCALE}} → locale WordPressa (pl, fr, en, es i inne)

Plik .envtmpl jest przy generowaniu przemianowywany na .env.example.

Zmienne środowiskowe do uzupełnienia ręcznie

Niektórych wartości nie da się pobrać automatycznie, musisz dodać je do pliku .env (tworzonego z .env.example):

WOO_REST_CONSUMER_KEY=ck_xxxxxxxxxxxxxx
WOO_REST_CONSUMER_SECRET=cs_xxxxxxxxxxxxxx
SESSION_PASSWORD=twoje-haslo-minimum-32-znaki

Wygeneruj mocne SESSION_PASSWORD:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Development lokalny

npm install
cp .env.example .env
# Edit .env and fill in the missing secrets
npm run dev

Frontend dostępny jest pod http://localhost:3000. Na czas developmentu dodaj ten adres do origins CORS po stronie WordPressa.

Wdrożenie na Vercel

npx vercel link
npx vercel env pull .env.production
npx vercel deploy --prod

Następnie skonfiguruj wszystkie zmienne środowiskowe w panelu Vercel (Project → Settings → Environment Variables). Dostarczony plik vercel.json ustawia region na cdg1 (Paryż) i wyłącza cache na trasach /api/*.

Wdrożenie na Hetznerze (albo dowolnym VPS Ubuntu/Debian)

# On the server, as root or with sudo
git clone your-repo.git storefront && cd storefront
cp .env.example .env
nano .env                       # Fill in all variables
bash deploy/hetzner.sh

Skrypt instaluje Dockera, jeśli trzeba, buduje obraz, uruchamia kontener i wystawia usługę na 127.0.0.1:3000. Dodaj Caddy albo nginx jako reverse proxy dla TLS. Przykład minimalnego Caddyfile:

sklep.przyklad.pl {
  encode zstd gzip
  reverse_proxy 127.0.0.1:3000
}

Udostępniane endpointy REST

Wszystkie endpointy wtyczki znajdują się w przestrzeni nazw dfhsk/v1. Pełny adres: https://przyklad.pl/wp-json/dfhsk/v1/…

Uwierzytelnianie

• POST /auth/login: body { username, password } → zwraca { token, refresh_token, user }
• POST /auth/refresh: body { refresh_token } → zwraca nowy token
• GET /auth/me: nagłówek Authorization: Bearer … → zwraca bieżącego użytkownika
• POST /auth/register: body { email, password, first_name, last_name }
• POST /auth/logout: unieważnia refresh token

Koszyk

Wszystkie wywołania przekazują token koszyka w nagłówku X-DFHSK-Cart. Serwer zwraca nowy token w tym samym nagłówku przy każdej odpowiedzi.

• GET /cart: pełna migawka (pozycje, sumy, podatki, koszty wysyłki)
• POST /cart/add: body { product_id, quantity, variation? }
• POST /cart/update: body { key, quantity }
• POST /cart/remove: body { key }
• POST /cart/coupon: body { code }
• DELETE /cart/coupon/{code}
• POST /cart/shipping: body { country, postcode } → zwraca obowiązujące stawki
• POST /cart/clear

Checkout

• POST /checkout/create-order: body { payment_method, billing, shipping? } → zwraca { order_id, order_key, redirect }. redirect to adres bramki płatności (Stripe, PayPal i inne).
• GET /checkout/order/{id}: wymagany nagłówek Authorization: Bearer …

Konfiguracja publiczna

• GET /config: dostępny bez uwierzytelniania. Zwraca { currency, base_country, countries, payment_methods, tax_settings }. Starter Next.js używa tego endpointu do zasilenia formularzy checkoutu.

Webhooki ISR (po stronie Next.js)

Wtyczka wysyła POST na {FRONTEND_URL}/api/revalidate z nagłówkiem Authorization: Bearer {REVALIDATE_TOKEN}. Ciało to JSON:

{
  "paths": ["/products/lniana-marynarka", "/products"],
  "tags": ["product:lniana-marynarka"],
  "reason": "wc_update_product"
}

Trasa /api/revalidate dostarczona w starterze weryfikuje token, a następnie wywołuje revalidatePath i revalidateTag dla każdej pozycji.

Personalizacja startera

Dostarczony kod objęty jest licencją GPL v2: możesz go modyfikować, rozszerzać i redystrybuować bez ograniczeń. Typowe punkty wejścia:

• Paleta kolorów: tailwind.config.ts, paleta brand (domyślnie pomarańczowa)
• Komponenty sklepu: src/components/shop/ (Header, Footer, ProductCard, CartProvider)
• Strony publiczne: src/app/(shop)/
• Strony konta klienta: src/app/(auth)/
• Formatowanie cen i dat: src/lib/format.ts
• Typy TypeScript: src/types/woo.ts
• Helper wywołań API: src/lib/woo-rest.ts (funkcje wooRest i dfhskFetch)

Rozwiązywanie problemów

Błąd CORS w konsoli przeglądarki

Origin frontendu nie znajduje się na białej liście. Dodaj go w Ustawienia → Origins CORS, po jednym w wierszu, bez końcowego ukośnika.

Webhooki ISR odpowiadają kodem 401

REVALIDATE_TOKEN po stronie Next.js nie odpowiada tokenowi skonfigurowanemu w WordPressie. Skopiuj dokładną wartość z ustawień WP do pliku .env w Next.js i wdróż ponownie.

Logowanie zwraca 403 mimo prawidłowych danych

Sprawdź, czy konto użytkownika ma ustawione hasło (a nie wyłącznie logowanie społecznościowe), czy HTTPS jest aktywne na produkcji i czy sekret JWT ma co najmniej 32 znaki. Zajrzyj do zakładki Diagnostyka.

Koszyk opróżnia się między stronami

W trybie JWT sprawdź, czy starter poprawnie odczytuje i zapisuje token w localStorage (klucz dfhsk_cart_token). Otwórz inspektora przeglądarki → zakładka Application → Local Storage.

Zamówienie utworzone w WooCommerce nie pojawia się po stronie Next.js

Sprawdź, czy zdarzenie Zamówienia jest zaznaczone w zdarzeniach ISR i czy webhook wychodzi bez błędu (włącz WP_DEBUG_LOG).

Co dalej

Starter to punkt wyjścia, nie gotowy produkt. Zależnie od projektu rozważ dodanie:

• Wyszukiwarki natychmiastowej (Algolia, Meilisearch, Typesense) zasilanej tymi samymi webhookami ISR
• Redakcyjnego CMS po stronie WordPressa z wtyczką ACF albo podobną i dedykowaną stroną Next.js
• PWA z service workerem do trybu offline (zobacz też nasz moduł dfpwa)
• Personalizacji AI w czasie rzeczywistym (zobacz dfsmartcontent)

W razie pytań technicznych skontaktuj się ze wsparciem DataFirefly, dołączając logi i wyniki z zakładki Diagnostyka.