Przejdź do głównej zawartości

Szybki start

Stwórz swój pierwszy storefront na platformie DoSwiftly w kilka minut — od instalacji CLI po działający serwer deweloperski.

Wymagania​

  • Node.js >= 22 (pobierz) — wymagane przez pipeline wdrożeniowy
  • Menedżer pakietów — pnpm (zalecany), npm, yarn lub bun (wybierasz w kreatorze init)
  • @doswiftly/cli — narzędzie wiersza poleceń do tworzenia, uruchamiania i wdrażania storefrontów (instalujesz w kroku 1)
  • @doswiftly/storefront-sdk — type-safe SDK do komunikacji z GraphQL API DoSwiftly (dołączany do wygenerowanego projektu)
  • Slug sklepu — identyfikator Twojego sklepu w DoSwiftly (np. moj-sklep)
  • Dostęp do API — adres GraphQL API DoSwiftly (otrzymasz od administratora platformy)

1. Zainstaluj CLI​

npm i -g @doswiftly/cli

Zweryfikuj instalację:

doswiftly --version

2. Stwórz nowy projekt​

doswiftly init

Kreator przeprowadzi Cię przez konfigurację:

  1. Nazwa projektu — nazwa folderu (np. moj-storefront)
  2. Szablon — wybierz jeden z dostępnych szablonów z listy (pobieranej z rejestru DoSwiftly)
  3. Shop slug — identyfikator Twojego sklepu
  4. Adres API — adres GraphQL API DoSwiftly

Kreator może też od razu zainstalować zależności. Po zakończeniu:

cd moj-storefront

3. Sprawdź konfigurację​

CLI zapisuje konfigurację projektu w .env.local. Upewnij się, że zmienne są poprawne:

# Kanon (dowolny framework) + aliasy Next.js — te same wartości
DOSWIFTLY_API_URL=https://api.doswiftly.pl
DOSWIFTLY_SHOP_SLUG=moj-sklep
NEXT_PUBLIC_API_URL=https://api.doswiftly.pl
NEXT_PUBLIC_SHOP_SLUG=moj-sklep

Pełny opis kontraktu zmiennych (kanon vs aliasy frameworkowe): Zmienne środowiskowe.

informacja

Przy uruchomieniu przez doswiftly dev zmienne środowiskowe są wstrzykiwane automatycznie — adres API jest wyznaczany według kolejności: zmienna shell → aktywny profil (doswiftly env use) → doswiftly.config.ts → .env.local. Plik .env.local jest potrzebny tylko przy bezpośrednim uruchomieniu serwera frameworka z pominięciem CLI. Szczegóły: Priorytet konfiguracji (API URL).

4. Uruchom serwer deweloperski​

Jeśli pominąłeś instalację zależności podczas init, zainstaluj je najpierw (pnpm install). Następnie uruchom serwer przez CLI:

doswiftly dev

Storefront będzie dostępny pod adresem http://localhost:3000.

Dlaczego doswiftly dev, a nie pnpm dev

doswiftly dev opakowuje serwer deweloperski frameworka, wstrzykuje rozwiązany adres API + slug sklepu i — gdy backend jest zdalny — uruchamia lokalne proxy, żeby ominąć CORS. Surowe pnpm dev uruchamia tylko framework, bez tej warstwy konfiguracji. Pełny opis: Przegląd CLI.

5. Pierwsze dane przez SDK​

Wygenerowany projekt zawiera @doswiftly/storefront-sdk (transport, providery, gotowe komponenty) oraz @doswiftly/storefront-operations (schemat + operacje GraphQL do codegen). SDK nie czyta zmiennych środowiskowych — adres API i slug przekazujesz jawnie w config.

Najprościej zacząć od pobrania danych po stronie serwera — klient serwerowy SDK nie wymaga providera:

import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';

const client = getStorefrontClient({
  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
  shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
});

// ProductsDocument generujesz lokalnie przez codegen ze schematu @doswiftly/storefront-operations
const data = await client.query(ProductsDocument);

Funkcje interaktywne (koszyk, autoryzacja, gotowe komponenty PriceDisplay / AddToCartButton, hook useCartManager) wymagają owinięcia aplikacji w StorefrontProvider — pełny setup opisuje SDK Overview. Wzorce pobierania danych i listę kolejnych kroków znajdziesz poniżej.

Następne kroki​