> ## Documentation Index
> Fetch the complete documentation index at: https://andcze.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

> [!TIP]
>
> 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](https://andcze.mintlify.site/pl/shop/domains.md) | 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](https://andcze.mintlify.site/pl/site/workspace.md#zasady-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.

> [!NOTE]
>
> 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`):

```bash theme={null}
# 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](https://andcze.mintlify.site/pl/site/limits.md)**
>
> Czas builda, rozmiary, AI.

> **[Domeny](https://andcze.mintlify.site/pl/shop/domains.md)**
>
> Własna domena dla strony.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.