# Headless Starter Kit: kompletny przewodnik

> Kompletny przewodnik po instalacji, konfiguracji i wdrożeniu Headless Starter Kit: wtyczki WordPressa, która zamienia Twój sklep WooCommerce w commerce headless, z gotowym, wstępnie skonfigurowanym starterem Next.js 15.

- Strona: <https://www.datafirefly.com/pl/documentation/headless-starter-kit/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/headless-starter-kit/index.md), [en](https://www.datafirefly.com/en/documentation/headless-starter-kit/index.md), [es](https://www.datafirefly.com/es/documentation/headless-starter-kit/index.md), [de](https://www.datafirefly.com/de/documentation/headless-starter-kit/index.md), [it](https://www.datafirefly.com/it/documentation/headless-starter-kit/index.md), [nl](https://www.datafirefly.com/nl/documentation/headless-starter-kit/index.md), [pt](https://www.datafirefly.com/pt/documentation/headless-starter-kit/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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.

**Dla kogo jest ten przewodnik.** Dla dewelopera, agencji albo technicznego sprzedawcy, który chce przenieść istniejący sklep WooCommerce na headless bez wymyślania od nowa uwierzytelniania, koszyka i checkoutu. Powinieneś swobodnie poruszać się w wierszu poleceń, znać Node.js i trochę konfiguracji serwera, jeśli wybierzesz Hetznera.

## 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+

**Klasyczny hosting współdzielony nie nadaje się** do hostowania frontendu Next.js, który wymaga trwałego runtime Node. Sama wtyczka WordPressa działa natomiast na dowolnym hostingu WP.

## 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`.

**Po ponownym wygenerowaniu sekretu JWT wszystkie istniejące tokeny dostępu i odświeżania stają się nieważne.** Użytkownicy będą musieli zalogować się ponownie. Uprzedź ich albo zrób to poza godzinami szczytu.

### 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
```

Dodaj `http://localhost:3000` na czas developmentu, a potem usuń go na produkcji.

### 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`)

Aby dodać nową stronę wypisującą na przykład produkty danej marki, zduplikuj `src/app/(shop)/products/page.tsx` i dostosuj zapytanie do WooCommerce REST. Funkcja `wooRest()` automatycznie obsługuje uwierzytelnianie Basic.

## 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.