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

# Własny kod i upload

> Wgraj własną stronę sklepu — zip, folder albo CLI — i podepnij ją do danych sklepu przez SDK.

Masz własny projekt albo stronę napisaną ręcznie? Wgraj ją do ItemShop — dostaniesz build, podgląd, hosting na domenie sklepu i dane sklepu przez SDK. Każdy upload tworzy nową rewizję, więc zawsze możesz wrócić do poprzedniej wersji.

## Cztery sposoby wgrania

**Zip**

**Workspace → Zmiany → Zip** — upuść plik `.zip` albo wybierz go z dysku. Archiwum może mieć do 25 MB (także po rozpakowaniu), do 5000 wpisów i 2000 plików projektu; wpis skompresowany ponad 200:1 jest odrzucany. Projekt musi mieć `itemshop.site.json` albo `index.html` w korzeniu. Ścieżki są sprawdzane — wpisy wychodzące poza projekt (`../`), absolutne, `node_modules/` i `.git/` są odrzucane.

**CLI**

```bash theme={null}
npx itemshop login
npx itemshop deploy
```

Pakuje projekt do zipa, wysyła go jako rewizję, buduje i wypisuje adres podglądu. Wymaga klucza API z uprawnieniem `site:write`. Szczegóły: [CLI](https://andcze.mintlify.site/pl/site/cli.md).

**GitHub**

**Workspace → Zmiany → GitHub → Połącz z GitHub** — zainstaluj aplikację ItemShop na wybranym repozytorium, wybierz repozytorium i gałąź. Szczegóły niżej.

**API**

```bash theme={null}
curl -X POST "https://itemshop.dev/api/v2/shops/<shopId>/site/upload?message=moja+zmiana" \
  -H "X-API-Key: <klucz>" -H "Content-Type: application/zip" \
  --data-binary @site.zip
```

Odpowiedź to nowa rewizja. Limit: 20 uploadów na 10 minut.

Po wgraniu ItemShop tworzy rewizję → uruchamia build → wdraża **podgląd**. Na produkcję trafia dopiero po kliknięciu **Opublikuj** (albo `itemshop deploy --prod`), chyba że masz włączony auto-deploy z gałęzi git.

## GitHub

Integracja korzysta z **aplikacji GitHub** — dostaje dostęp tylko do repozytoriów, które wskażesz, i tylko do zawartości (`Contents: read & write`). Odinstalowanie aplikacji w GitHubie automatycznie odłącza Workspace.

**1. Zainstaluj aplikację**

**Workspace → Zmiany → GitHub → Połącz z GitHub** przekierowuje na GitHub, gdzie wybierasz konto i repozytoria.

**2. Wybierz repozytorium i gałąź**

Wpisz `właściciel/nazwa` i gałąź.

**3. Wypychaj i pobieraj**

**Wypchnij szkic** tworzy commit na gałęzi, **Pobierz z GitHub** tworzy z gałęzi nową rewizję (autor: `git`).

Zasady synchronizacji:

* **Wypchnięcie** tworzy jeden commit (fast-forward, bez force). Gałąź staje się **lustrem strony** — pliki, które są tylko w repozytorium, znikają z gałęzi. Źródłem prawdy jest strona; jeśli trzymasz w repozytorium coś więcej, zrób pobranie przed edycją.
* **Pobranie** przyjmuje tylko zwykłe pliki (bez symlinków, submodułów, `node_modules/` i `.git/`) i sprawdza [limity](https://andcze.mintlify.site/pl/site/limits.md) przed pobraniem treści.
* **Auto-deploy z gałęzi** — przełącznik w **Zmiany → GitHub**: każdy push na połączoną gałąź (webhook podpisany HMAC) pobiera pliki w tle i buduje podgląd. Na produkcję trafia tylko wtedy, gdy w [zasadach publikacji](https://andcze.mintlify.site/pl/site/workspace.md#zasady-publikacji) włączysz auto-deploy z gałęzi i wyłączysz zatwierdzanie produkcji.
* Push wywołany przez samą platformę jest ignorowany, więc nie ma pętli.

> [!NOTE]
>
> Na instalacjach bez skonfigurowanej aplikacji GitHub (self-hosting) połączenie działa przez fine-grained token osobisty z uprawnieniem *Contents*. Bez uprawnienia *Webhooks* zostaje ręczna synchronizacja.

## Najprostsza strona: czysty HTML

Bez builda, bez npm — `index.html` w katalogu głównym wystarczy (projekt `static`). Hosting ma ścisłą politykę CSP (`script-src 'self'`), więc skrypt musi być osobnym plikiem z własnej domeny — bez skryptów inline i bez bibliotek z CDN:

```html index.html theme={null}
<!doctype html>
<html lang="pl">
  <head>
    <meta charset="utf-8" />
    <title>Mój sklep</title>
  </head>
  <body>
    <ul id="products"></ul>
    <script type="module" src="/app.js"></script>
  </body>
</html>
```

```js app.js theme={null}
// window.__ITEMSHOP__ wstrzykuje builder: { shopId, apiBase, locale, buildId }
const { shopId, apiBase } = window.__ITEMSHOP__;
const res = await fetch(`${apiBase}/storefront/v1/shops/${shopId}/products`);
const { data } = await res.json();

document.querySelector("#products").innerHTML = data.products
  .map((p) => `<li>${p.name} — ${p.price} ${p.currency}</li>`)
  .join("");
```

Chcesz SDK w projekcie `static`? Wgraj jego zbudowany plik ESM razem ze stroną i zaimportuj z `/`. Wygodniej jest jednak użyć projektu z buildem.

## Projekt z buildem (Vite + React)

Dodaj `itemshop.site.json` i używaj `@itemshop/sdk/react`:

```tsx src/App.tsx theme={null}
import { StorefrontProvider, useProducts, useCart } from "@itemshop/sdk/react";

function Products() {
  const { products } = useProducts();
  const cart = useCart();
  return products.map((p) => (
    <button key={p.id} onClick={() => cart.add(p)}>
      {p.name} — {p.price} {p.currency}
    </button>
  ));
}

export default function App() {
  return (
    <StorefrontProvider>
      <Products />
    </StorefrontProvider>
  );
}
```

Pełne API (kasa, rabaty, widżety, obsługa błędów): [SDK TypeScript](https://andcze.mintlify.site/pl/developers/sdk/typescript.md).

## Zasady, które musi spełnić strona

* **Tylko statyczny wynik.** Strona nie uruchamia kodu na serwerze. Dane pobiera w przeglądarce ze [Storefront API](https://andcze.mintlify.site/pl/developers/storefront-api.md).
* **Skrypty tylko z własnej domeny.** Polityka CSP zezwala na skrypty z domeny strony i z `challenges.cloudflare.com` (Turnstile); zapytania `fetch` na własną domenę i API platformy. Style i fonty: własne, Google Fonts; obrazy po `https:`. Szczegóły: [Build i hosting](https://andcze.mintlify.site/pl/site/build-hosting.md).
* **Bez sekretów.** Nie umieszczaj kluczy API w plikach strony — wszystko, co wgrasz, jest publiczne. CLI pomija `.env*`.
* **Płatności przez kasę ItemShop.** `sf.checkout.create(...)` zwraca `redirectUrl`; strona tylko przekierowuje gracza.
* **Zgody w kasie.** Formularz kasy musi zbierać akceptację regulaminu i zgodę na natychmiastową realizację (utrata prawa odstąpienia). Szablony robią to za Ciebie.
* **Zabronione pliki i skrypty.** Bez `node_modules/`, `.git/`, `.npmrc`/`.yarnrc`/`.pnpmfile.cjs`; `package.json` nie może mieć skryptów `preinstall`, `install`, `postinstall`, `prepare` itp.
* **Limity** rozmiaru i czasu builda: [Limity](https://andcze.mintlify.site/pl/site/limits.md).

## Co builder dodaje do strony

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

> **[CLI](https://andcze.mintlify.site/pl/site/cli.md)**
>
> `init`, `dev`, `deploy`, `pull`.

> **[Build i hosting](https://andcze.mintlify.site/pl/site/build-hosting.md)**
>
> Jak powstaje i gdzie działa strona.


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