Build i hosting

Jak ItemShop buduje stronę, gdzie ją hostuje, jak działa podgląd, publikacja i wycofanie zmian.

Każda zmiana strony przechodzi tę samą drogę: szkic → rewizja → build → wdrożenie podglądu → publikacja. Niezależnie od tego, czy zmianę zrobił AI edytor, agent przez MCP, upload, GitHub czy CLI.

​

Szkic i rewizje

Zmiany plików trafiają najpierw do szkicu (z autorem i czasem każdej zmiany). Zatwierdź szkic w Workspace → Zmiany, żeby zapisać niezmienną rewizję — numerowany snapshot wszystkich plików. Rewizji nigdy się nie edytuje; wycofanie to publikacja starszego wdrożenia. Różnice między rewizjami albo szkicem widzisz jako diff w tej samej zakładce.

​

Build

Build zamienia pliki projektu na statyczne HTML, CSS i JS. Trafia do kolejki, a wykonuje się w izolowanym kontenerze:

• npm ci --ignore-scripts i komenda z manifestu — skrypty instalacyjne pakietów nie są wykonywane,
• sieć tylko do rejestru npm (registry.npmjs.org), bez dostępu do sekretów i danych sklepu,
• 1 vCPU, 1 GiB RAM, ograniczona liczba procesów, brak uprawnień roota, twardy limit czasu 120 s,
• komenda builda z itemshop.site.json musi mieć postać npm run <skrypt>, vite build albo npx vite build.

Status builda: queued → building → ready albo failed. Przy failed zobaczysz log (do 1 MB) — AI edytor umie go przeczytać i naprawić błąd. Limity buildów zależą od planu: Free — 1 aktywny build naraz i 10 na godzinę, Pro — 2 naraz i 30 na godzinę (409 SITE_BUILD_BUSY, 429 SITE_BUILD_RATE_LIMIT). Buildy bez wdrożenia starsze niż 14 dni są usuwane razem z logiem i wynikiem, a niepodpięte pliki po 24 godzinach.

Projekt static (sam HTML/CSS/JS) nie ma kroku budowania ani sandboxa — pliki są publikowane tak, jak je wgrasz. Do każdego pliku HTML builder dokleja tylko skrypt konfiguracji.

​

Zmienne builda

Przy projektach vite-react builder ustawia jawne zmienne ITEMSHOP_* — odczytasz je w vite.config.ts lub kodzie (np. do tagów SEO). Projekty static nie mają kroku builda i ich nie dostają.

Zmienna	Wartość
ITEMSHOP_SITE_URL	Adres produkcyjny sklepu (origin, bez ścieżki): własna domena albo https://<nazwa-sklepu>.itemshop.site — także gdy build trafia na podgląd
ITEMSHOP_SHOP_NAME	Nazwa wyświetlana sklepu
ITEMSHOP_SHOP_ID	Identyfikator sklepu
ITEMSHOP_LOCALE	Domyślny język
ITEMSHOP_CURRENCY	Waluta sklepu
ITEMSHOP_API_BASE	Adres API (https://itemshop.dev/api/v2)

W przeglądarce shopId i adres API dalej pochodzą z /itemshop.config.js — zmienne ITEMSHOP_* istnieją tylko w czasie builda.

​

Co builder dodaje

Element	Zawartość
/itemshop.config.js	window.__ITEMSHOP__ = { shopId, apiBase, locale, buildId }, ładowany przez <script> na początku <head> każdego HTML. SDK czyta go automatycznie.
/itemshop.data.json	Snapshot sklepu i produktów z chwili builda — do SEO i szybkiego pierwszego renderu.

​

Podgląd i produkcja

Wdrożenie	Adres	Kto widzi
Podgląd	preview-<id-wdrożenia>.itemshop.site	Każdy, kto ma link — nie jest indeksowany (noindex). W panelu podgląd jest osadzony w ramce.
Produkcja	<nazwa-sklepu>.itemshop.site albo własna domena	Gracze.

Domena itemshop.site jest inna niż domena panelu (itemshop.dev), więc kod strony nigdy nie ma dostępu do ciasteczek panelu. Każdy build może mieć wiele podglądów. Produkcja wskazuje dokładnie jedno wdrożenie. Własne domeny działają tak jak dotąd (weryfikacja TXT / Cloudflare), bez dodatkowej konfiguracji.

​

Publikacja

Opublikuj w panelu (albo itemshop deploy --prod) przepina produkcję na wybrane wdrożenie. Z klucza API, tokenu MCP, CLI lub agenta AI produkcja podlega zasadom publikacji: przy włączonym zatwierdzaniu (domyślnie) odpowiedź to 403 WORKSPACE_PRODUCTION_REQUIRES_APPROVAL, więc itemshop deploy --prod zadziała dopiero po wyłączeniu tej opcji albo promocji w panelu. Sesja panelu zawsze może publikować. Gracze zobaczą nową wersję po odświeżeniu strony (dokumenty HTML są zawsze rewalidowane, zasoby w assets/ są cache’owane bezterminowo).

​

Zasady publikacji

W Workspace → Publikacje ustawiasz, jak zmiany trafiają do graczy:

Ustawienie	Działanie
Podgląd przy każdym commicie	Każda nowa rewizja od razu dostaje build i adres podglądu.
Produkcja wymaga zatwierdzenia	Na produkcję trafia tylko to, co ręcznie promujesz.
Auto-deploy z gałęzi git	Zielony build z połączonej gałęzi GitHub trafia od razu na produkcję.

Log builda widzisz na żywo w tej samej zakładce.

​

Wycofanie zmian

Rollback to ponowna publikacja starszego wdrożenia: Workspace → Publikacje → wybierz wdrożenie → Przywróć. Nic nie jest budowane od nowa, więc zmiana trwa sekundy. Wycofane wdrożenie zostaje na liście, więc możesz do niego wrócić.

​

Bezpieczeństwo strony

• Hostowany jest wyłącznie statyczny wynik — żaden kod ze strony nie działa na serwerach ItemShop, a serwer hostingu odpowiada tylko na odczyt.

• Nagłówek Content-Security-Policy każdej strony zawiera m.in.:

  Dyrektywa	Dozwolone
  script-src	własna domena i challenges.cloudflare.com (Turnstile) — bez skryptów inline
  connect-src	własna domena, API platformy i challenges.cloudflare.com
  style-src	własna domena, style inline i fonts.googleapis.com
  font-src	własna domena, data: i fonts.gstatic.com
  img-src	własna domena, data:, blob: i dowolny https:
  frame-src	challenges.cloudflare.com i discord.com (widżet)
  object-src, base-uri	zablokowane / tylko własna domena
  frame-ancestors	produkcja — tylko ona sama; podgląd — panel

• Do odpowiedzi dochodzą X-Content-Type-Options: nosniff, Referrer-Policy i COOP. Na domenach sklepów nie ma ciasteczek platformy.

• Sklep zablokowany lub nieaktywny zwraca 404.

Strona musi więc ładować skrypty ze swojej domeny i łączyć się tylko z własną domeną i API ItemShop. Biblioteka z CDN albo skrypt inline zostaną zablokowane przez przeglądarkę — dodaj je do projektu i zbuduj razem ze stroną.

​

Przez API

Ten sam przepływ jest dostępny przez API z kluczem (site:write):

# build szkicu
curl -X POST https://itemshop.dev/api/v2/shops/<shopId>/site/builds \
  -H "X-API-Key: <klucz>" -H "Content-Type: application/json" \
  -d '{ "revisionId": "draft" }'

# wdrożenie builda jako podgląd
curl -X POST https://itemshop.dev/api/v2/shops/<shopId>/site/deployments \
  -H "X-API-Key: <klucz>" -H "Content-Type: application/json" \
  -d '{ "buildId": "<buildId>", "kind": "preview" }'

# publikacja (lub rollback) wdrożenia
curl -X POST https://itemshop.dev/api/v2/shops/<shopId>/site/deployments/<deploymentId>/promote \
  -H "X-API-Key: <klucz>"

Limity

Czas builda, rozmiary, AI.

Domeny

Własna domena dla strony.