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

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.

GitHub

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

API

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

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:

index.html

<!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>

app.js

// 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:

src/App.tsx

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.

​

Zasady, które musi spełnić strona

• Tylko statyczny wynik. Strona nie uruchamia kodu na serwerze. Dane pobiera w przeglądarce ze Storefront API.
• 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.
• 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.

​

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

init, dev, deploy, pull.

Build i hosting

Jak powstaje i gdzie działa strona.