Deweloper Storefront

Dla Ciebie jeśli...

Budujesz sklep internetowy dla klienta lub własny storefront na platformie DoSwiftly. Używasz @doswiftly/cli do scaffoldingu projektu i @doswiftly/storefront-sdk do komunikacji z GraphQL API.

Czego potrzebujesz

• Node.js >= 22 (pobierz) — wymagany przez pipeline wdrożeniowy (Cloudflare Workers / Wrangler). Sam CLI działa już od Node 18, ale doswiftly deploy potrzebuje 22.
• Menedżer pakietów — pnpm (zalecany); CLI wspiera też npm, yarn i bun (wybierasz w kreatorze init)
• Slug sklepu — identyfikator Twojego sklepu w DoSwiftly (np. moj-sklep)
• Dostęp do API — adres GraphQL API DoSwiftly (otrzymasz od administratora platformy)

Nie potrzebujesz

• Docker
• Klonowania repozytorium
• Znajomości wewnętrznej architektury platformy

Twoja ścieżka

Zalecana kolejność dla nowego storefrontu — od scaffoldingu, przez pierwsze dane, do pełnego checkoutu:

1. Szybki start — doswiftly init → działający serwer deweloperski w kilka minut
2. CLI — przegląd — środowiska, profile, wdrażanie na Cloudflare Workers
3. Przegląd SDK — architektura warstwowa, hooki i stores
4. Produkty — listy, szczegóły, wyszukiwanie i filtry
5. Koszyk — dodawanie pozycji, auto-recovery, Zustand store
6. Checkout — adres → wysyłka → płatność → finalizacja zamówienia
7. Logowanie i konto klienta — rejestracja, sesja (httpOnly cookie), panel klienta
8. Zamówienia — podsumowanie po checkout (gość bez konta + zalogowany)
9. Więcej funkcji — kolekcje, marki, karty podarunkowe, program lojalnościowy, zwroty
10. API Reference — pełna dokumentacja GraphQL API (auto-generowana ze schematu)

Technologie

Storefronty na platformie DoSwiftly są budowane z użyciem:

Warstwa	Technologia
Framework	Next.js 16, React 19
SDK	@doswiftly/storefront-sdk (transport, providery, stores, cache)
Operacje GraphQL	@doswiftly/storefront-operations (schemat + nazwane operacje do codegen)
State management	Zustand
Styling	Tailwind CSS v4, shadcn/ui
Typowanie	TypeScript, GraphQL Code Generator
Deployment	Cloudflare Workers + R2 (doswiftly deploy)

Główne komponenty

Storefront SDK

Layered runtime SDK (aktualna linia v17.x) z 0 runtime dependencies w core:

• Core — createStorefrontClient(), composable middleware pipeline, CartClient, AuthClient, StorefrontError, strategie cache
• React adapter — StorefrontProvider, Zustand stores (auth, currency, language, cart), useAuth(), useCartManager(), useCurrency() + gotowe komponenty headless (PriceDisplay, AddToCartButton, Money, Image)
• Cache — cacheLong(), cacheShort(), cacheNone(), cachePrivate()
• Hooki React Query i server helpers są generowane lokalnie w szablonie przez codegen z operacji GraphQL (wzorzec codegen-first) — SDK nie eksportuje gotowych hooków GraphQL

DoSwiftly CLI

Narzędzie wiersza poleceń do:

• Tworzenia nowych projektów (doswiftly init)
• Zarządzania środowiskami (doswiftly env)
• Uruchamiania serwera deweloperskiego z proxy CORS (doswiftly dev)
• Wdrażania storefrontu (doswiftly deploy)
• Tworzenia środowisk podglądu (doswiftly preview)

Szybki przykład

// Server Component — lokalne server helpers (wygenerowane z codegen)
import { fetchProducts } from '@/lib/graphql/server';

export default async function ProductsPage() {
  const { products } = await fetchProducts({ first: 20 });

  return (
    <div className="grid grid-cols-4 gap-4">
      {products.map((product) => (
        <div key={product.id}>
          <h2>{product.title}</h2>
          <p>
            {product.priceRange.minVariantPrice.amount}{' '}
            {product.priceRange.minVariantPrice.currencyCode}
          </p>
        </div>
      ))}
    </div>
  );
}

// Client Component — lokalne hooki React Query (wygenerowane z codegen)
'use client';
import { useProducts, useCartAddLines } from '@/lib/graphql/hooks';

export function ProductList({ cartId }: { cartId: string }) {
  const { data, isLoading } = useProducts({ first: 10 });
  const addToCart = useCartAddLines();

  if (isLoading) return <div>Ładowanie...</div>;

  return (
    <div>
      {data?.products.map((product) => (
        <button
          key={product.id}
          onClick={() =>
            addToCart.mutateAsync({
              id: cartId, // mutacje koszyka przyjmują `id`, nie `cartId`
              lines: [{ variantId: product.variants.nodes[0].id, quantity: 1 }], // variants to Connection → .nodes
            })
          }
        >
          {product.title}
        </button>
      ))}
    </div>
  );
}

W praktyce nie zarządzasz cartId ręcznie

Powyższy przykład pokazuje surowy hook. W realnym storefroncie użyj useCartManager() z SDK — trzyma cartId w cookie, robi auto-init i auto-recovery wygasłych koszyków. Patrz Koszyk.