CLI — Przegląd

DoSwiftly CLI (@doswiftly/cli) to narzędzie wiersza poleceń do tworzenia, konfigurowania i zarządzania projektami storefront opartymi na platformie DoSwiftly.

Instalacja

npm i -g @doswiftly/cli

Po zainstalowaniu polecenie doswiftly będzie dostępne globalnie w terminalu.

Szybki start

Tworzenie nowego projektu

doswiftly init

Polecenie doswiftly init uruchamia interaktywny kreator, który przeprowadzi Cię przez:

1. Nazwę projektu — nazwa katalogu i paczki package.json
2. Wybór szablonu — gotowy szablon storefront (szczegóły poniżej)
3. Konfigurację sklepu — slug sklepu i adres API
4. Instalację zależności — automatyczne uruchomienie pnpm install

Wybór szablonu

Lista dostępnych szablonów jest pobierana z rejestru DoSwiftly w trakcie działania kreatora (doswiftly init) — nie jest zaszyta na stałe w CLI. Kreator pokazuje tylko opublikowane szablony wraz z biblioteką UI, opisem i wersją. Możesz też:

• podać szablon wprost flagą --template <nazwa>,
• pominąć rejestr (--no-remote) i zacząć od pustego / lokalnego szablonu.

Wygenerowany projekt zawiera:

• Prekonfigurowany @doswiftly/storefront-sdk + @doswiftly/storefront-operations
• Lokalny codegen (codegen.ts) generujący hooki React Query i server helpers z operacji GraphQL (SDK nie dostarcza gotowych hooków GraphQL — powstają lokalnie w projekcie)
• Konfigurację projektu (doswiftly.config.ts) i środowiskową (.env.local)
• Strukturę katalogów zgodną z App Router (Next.js 16)

Pobranie z połączonego repozytorium

Jeśli sklep wybrany w kreatorze ma połączone repozytorium GitHub, w kroku „Źródło kodu" pojawi się dodatkowa opcja pobrania kodu wprost z tego repozytorium — przydatna, gdy chcesz kontynuować pracę nad istniejącym storefrontem zamiast zaczynać od pustego projektu lub szablonu.

Kreator klonuje repozytorium z pełną historią, korzystając z Twojego lokalnego dostępu do GitHub: używa GitHub CLI (gh), jeśli jest zainstalowane (samo obsługuje logowanie), a w przeciwnym razie polecenia git z lokalnie skonfigurowanymi poświadczeniami. Po sklonowaniu dopisuje brakujące zmienne do .env.local (bez nadpisywania istniejących wartości) i tworzy doswiftly.config.ts.

Jeśli sklep nie ma połączonego repozytorium, ta opcja po prostu się nie pojawia. Gdy klonowanie się nie powiedzie (najczęściej z powodu braku dostępu do prywatnego repozytorium), kreator pokaże instrukcję — zaloguj się przez gh auth login albo skonfiguruj poświadczenia git, i upewnij się, że masz uprawnienia do tego repozytorium.

Tryby inicjalizacji

Polecenie init działa w trzech trybach w zależności od stanu uwierzytelniania:

1. Login mode (zalecany) — po zalogowaniu (doswiftly auth login) CLI pobiera listę zespołów i projektów z API, umożliwiając interaktywny wybór.
2. Demo mode — tryb lokalnego developmentu bez połączenia z API. Używa wbudowanej konfiguracji demo.
3. Manual mode — zaawansowany tryb, w którym ręcznie podajesz slug sklepu i adres API.

Po scaffoldingu

Po utworzeniu plików projektu CLI automatycznie inicjalizuje repozytorium Git (git init) z początkowym commitem. Inicjalizacja Git jest pomijana, jeśli git nie jest dostępny lub projekt powstaje wewnątrz istniejącego repozytorium.

Uwierzytelnianie

doswiftly auth login

Polecenie auth login uruchamia przepływ logowania OAuth:

1. CLI otwiera przeglądarkę z adresem logowania DoSwiftly
2. Lokalny serwer callback nasłuchuje na porcie 8477
3. Po pomyślnym logowaniu token jest zapisywany automatycznie

doswiftly auth logout

Polecenie auth logout usuwa zapisane tokeny i kończy sesję.

wskazówka

Upewnij się, że port 8477 nie jest zablokowany przez firewall ani zajęty przez inny proces.

GitHub i CI/CD

doswiftly auth github    # Połącz konto GitHub (device flow)
doswiftly auth token --deploy  # Generuj token deploy dla CI/CD

Połączenie konta GitHub umożliwia automatyczne wdrażania przez webhooki (push → production, PR → preview). Token deploy służy do integracji z pipeline'ami CI/CD.

Plik konfiguracyjny

CLI przechowuje całą konfigurację globalną — profile środowiskowe wraz z tokenami uwierzytelniania per profil — w jednym pliku:

~/.config/doswiftly/profiles.json

Plik (format v2) zawiera listę profili; każdy profil ma apiUrl, opcjonalny opis, zmienne ustawione przez env set oraz dane zalogowanego konta (email, userId, token, data wygaśnięcia) — per profil. Starsze instalacje z osobnymi plikami config.json + environments.json są przy pierwszym uruchomieniu automatycznie migrowane do tego formatu.

uwaga

Nie edytuj profiles.json ręcznie, chyba że wiesz co robisz. Używaj poleceń doswiftly auth i doswiftly env do zarządzania konfiguracją. Nie commituj tego pliku ani nie udostępniaj publicznie — zawiera tokeny sesji.

---

Środowiska

DoSwiftly CLI umożliwia zarządzanie wieloma profilami środowiskowymi, co pozwala łatwo przełączać się między konfiguracjami dev, staging i production.

Czym są profile środowiskowe?

Każdy profil środowiskowy to zestaw konfiguracji zawierający:

• name — nazwa profilu (np. dev, staging, production)
• apiUrl — adres backendu DoSwiftly (np. http://localhost:8000 lub https://api.doswiftly.pl)
• isActive — czy profil jest aktywny
• createdAt — data utworzenia
• description (opcjonalnie) — opis profilu
• variables (opcjonalnie) — dowolne zmienne środowiskowe ustawiane przez env set
• account (opcjonalnie) — dane zalogowanego konta (email, token) — per profil

Slug sklepu nie jest częścią profilu — slug jest właściwością projektu, przechowywany w doswiftly.config.ts (shop.slug). Ten sam profil (np. dev wskazujący na lokalny backend) może być współdzielony przez wiele projektów z różnymi slugami.

Profile są przechowywane w pliku:

~/.config/doswiftly/profiles.json

Priorytet konfiguracji (API URL)

Kiedy uruchomisz doswiftly dev, doswiftly inspect lub doswiftly proxy, CLI rezolwuje adres API według następującej kolejności (pierwsza pasująca wartość wygrywa):

#	Źródło	Zastosowanie
1	Zmienna shell DOSWIFTLY_API_URL lub (dla doswiftly dev) NEXT_PUBLIC_API_URL	Jednorazowe/CI-owe nadpisanie: DOSWIFTLY_API_URL=… doswiftly dev
2	Aktywny profil (doswiftly env use <nazwa>)	Jawne przełączenie środowiska przez developera
3	api.url w doswiftly.config.ts	Baseline ustalony podczas doswiftly init
4	NEXT_PUBLIC_API_URL w .env.local	Rzadki fallback per-projekt
5	Domyślny (http://localhost:8000 dla dev, https://api.doswiftly.pl dla pozostałych)	Ostatnia deska ratunku

Dlaczego profil wygrywa z doswiftly.config.ts: wywołanie doswiftly env use dev jest jawną akcją dewelopera — musi mieć pierwszeństwo nad pasywnym, zahardkodowanym w projekcie baseline'em. Zmienne shell stoją jeszcze wyżej, żeby obsługiwać CI/CD i jednorazowe eksperymenty bez edycji plików.

doswiftly deploy używa innej kolejności: tutaj doswiftly.config.ts wygrywa z aktywnym profilem (deploy jest operacją "na projekt", nie "na środowisko"). Tylko zmienna DOSWIFTLY_API_URL może nadpisać api.url przy deployu.

Jak to zweryfikować: banner doswiftly dev wypisuje przyrostek pokazujący źródło, np.:

API:         http://localhost:8000 (from profile "dev")
API Proxy:   http://localhost:4001 (from env NEXT_PUBLIC_API_URL)
              -> https://api.doswiftly.pl

Jeśli widzisz, że po doswiftly env use dev banner nadal pokazuje adres produkcyjny z przyrostkiem (from doswiftly.config.ts), oznacza to, że config projektu ma hardcoded api.url — usuń go z doswiftly.config.ts albo polegaj wyłącznie na profilach (CLI wypisuje ostrzeżenie przy doswiftly env use, gdy wykryje taką kolizję).

Konflikt portu serwera deweloperskiego

Jeśli port 3000 (lub inny ustawiony w dev.port) jest zajęty, doswiftly dev automatycznie znajdzie następny wolny w zakresie +10 i wypisze ostrzeżenie:

⚠ Port 3000 is in use, using 3001 instead
  Pass --strict-port to fail fast instead of auto-falling back.

  Storefront:  http://localhost:3001

Aby wymusić zachowanie fail-fast (np. w CI), przekaż --strict-port albo ustaw dev.strictPort: true w doswiftly.config.ts. Gdy cały zakres 10 portów jest zajęty, CLI zakończy z kodem 1 i actionable komunikatem — zatrzymaj konfliktujący proces lub przekaż --port <N>.

Testowanie płatności PayU / Przelewy24 w trybie sandbox

Domyślnie storefront uruchomiony przez doswiftly dev (lub pnpm dev w template) próbujący createPayment z returnUrl: 'http://localhost:3000/checkout/success' blokowany jest przez backend komunikatem "Adres powrotu musi prowadzić do zweryfikowanej domeny sklepu" — open-redirect protection dla production. Storefront-developer pracujący z sandbox PayU / Przelewy24 może obejść tę blokadę bez kompromitacji production security.

Backend (post-2026-05-28) automatycznie zezwala localhost returnUrl/cancelUrl TYLKO gdy:

1. Provider w admin sklepu skonfigurowany w trybie sandbox (environment: 'sandbox')
2. URL hostname to localhost (localhost, 127.0.0.1, ::1, dowolny port)

Production credentials + localhost URL → nadal RETURN_URL_INVALID (zero security regression dla real money flow). Każdy bypass jest forensycznie audytowany.

Tworzenie profilu

doswiftly env add [nazwa]

Polecenie uruchomi interaktywny kreator, który zapyta o:

1. Nazwę profilu (jeśli nie podano jako argument)
2. Adres API (apiUrl)
3. Opcjonalny opis

Slug sklepu nie jest częścią profilu — żyje w doswiftly.config.ts projektu (shop.slug). Jeśli potrzebujesz NEXT_PUBLIC_SHOP_SLUG jako zmiennej, ustaw ją osobno: doswiftly env set NEXT_PUBLIC_SHOP_SLUG <slug>.

Przykład:

doswiftly env add staging

? API URL: https://staging-api.doswiftly.pl
? Opis (opcjonalnie): Środowisko stagingowe
✓ Środowisko "staging" zostało dodane.

Przełączanie środowisk

doswiftly env use <nazwa>

Po przełączeniu wszystkie kolejne polecenia CLI (w tym doswiftly dev, doswiftly deploy run, doswiftly preview create) będą korzystać z ustawień wybranego profilu.

Przykład:

doswiftly env use production

✓ Aktywne środowisko: production
  API URL: https://api.doswiftly.pl
  Shop slug: moj-sklep

Lista środowisk

doswiftly env list

Wyświetla wszystkie skonfigurowane profile z zaznaczeniem aktywnego:

  dev          http://localhost:3000        moj-sklep-dev
▸ staging      https://staging.doswiftly.pl  moj-sklep-staging
  production   https://api.doswiftly.pl   moj-sklep

Generowanie pliku .env.local

doswiftly env generate

Generuje plik .env.local na podstawie aktywnego profilu. Jeśli plik już istnieje, CLI pyta o potwierdzenie nadpisania. Zapisywane są obie formy kontraktu — kanon DOSWIFTLY_API_URL/DOSWIFTLY_SHOP_SLUG oraz aliasy NEXT_PUBLIC_* (te same wartości; adres z apiUrl profilu, slug z doswiftly.config.ts) — a także wszystkie zmienne ustawione przez env set. Pełny kontrakt: Zmienne środowiskowe.

Usuwanie profilu

doswiftly env delete [name]

Usuwa wskazany profil środowiskowy. Wyświetla interaktywną listę do wyboru i prosi o potwierdzenie przed usunięciem.

Ustawianie zmiennych środowiskowych

doswiftly env set <KLUCZ> <WARTOŚĆ>

Ustawia dowolną zmienną środowiskową w aktywnym profilu. Zmienne są przechowywane w polu variables profilu i:

• Uwzględniane w pliku .env.local generowanym przez doswiftly env generate
• Dostępne dla procesu Next.js po uruchomieniu pnpm dev (jeśli wcześniej wygenerowano .env.local)

Jeśli nie istnieje aktywny profil, CLI wyświetli błąd z instrukcją utworzenia profilu.

Przykład:

doswiftly env set NEXT_PUBLIC_API_URL https://api.doswiftly.pl
doswiftly env set NEXT_PUBLIC_SHOP_SLUG moj-sklep
doswiftly env set CUSTOM_ANALYTICS_KEY abc123

Najważniejsze zmienne:

Zmienna	Opis	Przykład
NEXT_PUBLIC_API_URL	Adres API backendu	https://api.doswiftly.pl
NEXT_PUBLIC_SHOP_SLUG	Slug sklepu	moj-sklep

Typowy workflow

Poniżej przedstawiony jest typowy scenariusz pracy z wieloma środowiskami:

1. Konfiguracja początkowa

# Środowisko lokalne (tworzone automatycznie przez doswiftly init)
# Interaktywny kreator pyta o API URL i shop slug
doswiftly env add dev

# Środowisko staging
doswiftly env add staging

# Środowisko produkcyjne
doswiftly env add production

# Ustawienie zmiennych produkcyjnych
doswiftly env use production
doswiftly env set NEXT_PUBLIC_API_URL https://api.doswiftly.pl
doswiftly env set NEXT_PUBLIC_SHOP_SLUG moj-sklep

# Generowanie pliku .env.local z aktywnego profilu
doswiftly env generate

2. Codzienna praca

# Praca lokalna
doswiftly env use dev
doswiftly dev

# Testowanie na staging
doswiftly env use staging
doswiftly preview create

# Wdrożenie na produkcję
doswiftly env use production
doswiftly deploy run

uwaga

Plik profiles.json zawiera konfiguracje środowisk oraz tokeny uwierzytelniania (per profil). Nie udostępniaj go publicznie ani nie dodawaj do repozytorium.

---

Wdrażanie i podgląd

Ten przewodnik opisuje pełny workflow wdrażania storefront — od inicjalizacji projektu, przez środowiska podglądu, aż po produkcyjne wdrożenie z własną domeną.

Pełny workflow

doswiftly init → doswiftly dev → doswiftly preview create → doswiftly deploy run → doswiftly config domain add

1. Inicjalizacja — doswiftly init tworzy projekt z wybranym szablonem
2. Rozwój lokalny — doswiftly dev uruchamia serwer deweloperski
3. Podgląd — doswiftly preview create tworzy tymczasowe środowisko do testów
4. Wdrożenie — doswiftly deploy run buduje i publikuje storefront
5. Domena — doswiftly config domain add podpina własną domenę

Wdrażanie produkcyjne

doswiftly deploy run

Główne polecenie wdrażania. Wykonuje wieloetapowy pipeline: pre-checks, build, manifest, upload, activate, poll. Wdrażanie odbywa się na Cloudflare Workers.

Domyślna komenda

doswiftly deploy jest równoważne z doswiftly deploy run.

doswiftly deploy rundomyślna komenda

Deploy storefront to Cloudflare Workers

doswiftly deploy run [options]

Flaga	Domyślnie	Opis
--type <type>	PRODUCTION	Deployment type (PRODUCTION, PREVIEW, STAGING)
--provider <provider>	—	Cloud provider deprecated
--branch <branch>	—	Git branch to deploy
--message <message>	—	Deployment message

Co się dzieje po uruchomieniu:

1. Pre-deployment checks — walidacja projektu (szczegóły poniżej)
2. Codegen i publikacja trusted documents — jeśli projekt ma skonfigurowany codegen, CLI generuje typowane dokumenty operacji i publikuje manifest trusted documents do API — zanim ruszy build. Projekt bez codegenu: krok jest cicho pomijany. Publikacja się nie uda → deploy przerywa się od razu (błąd fatalny)
3. Build — uruchomienie buildu za pomocą OpenNext Cloudflare
4. Create deployment — wysłanie zadania do API z branchem, commitem, typem i kluczem idempotentności
5. Manifest — generowanie content-hash manifest (SHA-256 per plik) i wysłanie do API; API zwraca listę assetów, których jeszcze nie ma po swojej stronie
6. Upload — spakowanie buildu do archiwum tar.gz i wysłanie go bezpośrednio do magazynu platformy pod krótkotrwałym podpisanym adresem. Artefakt nie przechodzi przez API, więc rozmiar buildu nie zderza się z limitami wielkości żądań HTTP. Po wysłaniu platforma weryfikuje rozmiar i przetwarza artefakt w tle; CLI czeka na potwierdzenie gotowości, zanim ruszy aktywacja
7. Activate — platforma przełącza ruch sklepu na nową wersję
8. Polling — CLI sprawdza status co 5 sekund, maksymalnie przez 10 minut
9. Wynik — wyświetlenie URL wdrożenia lub komunikatu o błędzie

Duży build? Zaktualizuj CLI

Tor bezpośredniego uploadu wybiera platforma i CLI korzysta z niego automatycznie — nie wymaga żadnej konfiguracji po Twojej stronie. Starsze wersje CLI wysyłają artefakt przez API i podlegają limitowi wielkości żądania (objaw: błąd 413 na etapie uploadu). Jeśli Twój build urósł, zaktualizuj pakiet: npm i -g @doswiftly/cli@latest (workflow generowany przez platformę używa @latest, więc aktualizuje się sam).

Stany wdrożenia

Podczas pollingu CLI raportuje bieżący stan:

Stan	Opis
PENDING	Wdrożenie oczekuje w kolejce
BUILDING	Trwa budowanie aplikacji
UPLOADING	Artefakt buildu jest wysyłany i przetwarzany po stronie platformy
DEPLOYING	Worker jest wdrażany na Cloudflare
DEPLOYED	Wdrożenie zakończone sukcesem
FAILED	Wdrożenie nie powiodło się — sprawdź logi

Sprawdzenie statusu

doswiftly deploy status [deploymentId]

Wyświetla aktualny stan ostatniego wdrożenia, URL, wersję i timestamp. Można podać konkretny deploymentId.

Logi wdrożenia

doswiftly deploy logs <deploymentId>

Wyświetla logi z procesu budowania i wdrażania dla wskazanego wdrożenia. Przydatne do diagnostyki błędów.

Wycofanie wdrożenia

doswiftly deploy rollback [deploymentId]

Przywraca poprzednią wersję storefront. Kopiuje manifest i referencje Cloudflare bez ponownego budowania. Przydatne gdy nowe wdrożenie zawiera błędy.

Kontrole przed wdrożeniem (pre-deployment checks)

Przed rozpoczęciem budowania CLI automatycznie weryfikuje:

Kontrola	Opis
package.json	Plik musi istnieć w katalogu projektu
Skrypt build	package.json musi zawierać skrypt build
Next.js	Projekt musi korzystać z Next.js
@doswiftly/storefront-sdk	SDK musi być zainstalowane jako zależność
NEXT_PUBLIC_API_URL	Zmienna musi być ustawiona w aktywnym środowisku
NEXT_PUBLIC_SHOP_SLUG	Zmienna musi być ustawiona w aktywnym środowisku

Jeśli którykolwiek z warunków nie jest spełniony, CLI wyświetli komunikat błędu i przerwie wdrażanie.

wskazówka

Uruchom doswiftly verify przed wdrożeniem, aby sprawdzić konfigurację projektu bez rozpoczynania budowania.

Środowiska podglądu (Preview)

Środowiska podglądu są realizowane jako wdrożenia z typem PREVIEW. Polecenia preview delegują do tego samego pipeline'u co deploy run, ale z typem PREVIEW i konfigurowalnym TTL.

Każde środowisko otrzymuje unikalny adres w formacie preview-{deploymentId}.doswiftly.pl.

Tworzenie podglądu

Domyślna komenda

doswiftly preview jest równoważne z doswiftly preview create.

doswiftly preview createdomyślna komenda

Create a preview deployment

doswiftly preview create [options]

Flaga	Domyślnie	Opis
--branch <branch>	—	Git branch to preview
--ttl <hours>	168	Time to live in hours (default: 168 / 7 days)

Tworzy nowe środowisko podglądu. CLI wykonuje pełny pipeline deploy z typem PREVIEW.

Lista podglądów

doswiftly preview list

Wyświetla wszystkie aktywne środowiska podglądu z ich URL, typem, wersją, statusem i datą wygaśnięcia.

Otwieranie podglądu

doswiftly preview open <previewId>

Otwiera wskazane środowisko podglądu w domyślnej przeglądarce.

Logi podglądu

doswiftly preview logs <previewId>

Wyświetla logi z procesu budowania podglądu.

Zatrzymywanie podglądu

doswiftly preview stop <previewId>

Zatrzymuje i usuwa środowisko podglądu, zwalniając zasoby Cloudflare.

informacja

Wygasłe środowiska podglądu są automatycznie czyszczone co godzinę. Job usuwania kasuje Worker i assety R2, a następnie oznacza wdrożenie jako EXPIRED.

Własna domena

Po wdrożeniu storefront możesz podpiąć własną domenę zamiast korzystać z domyślnego adresu *.doswiftly.pl.

Dodawanie domeny

doswiftly config domain add <domena>

Przykład:

doswiftly config domain add sklep.mojafirma.pl

Po uruchomieniu CLI wyświetli instrukcje konfiguracji DNS:

Dodaj następujący rekord CNAME w ustawieniach DNS:

  Typ:     CNAME
  Nazwa:   sklep
  Wartość: storefronts.doswiftly.pl

Po dodaniu rekordu, certyfikat SSL zostanie wystawiony automatycznie.
Propagacja DNS może zająć do 24 godzin.

Weryfikacja domeny odbywa się automatycznie co 5 minut. Po weryfikacji domena zostaje aktywowana, a mapowanie hostname → shop jest zapisywane w Cloudflare KV.

Lista domen

doswiftly config domain list

Wyświetla listę wszystkich domen z ich statusem (PENDING, ACTIVE, FAILED), stanem SSL i oznaczeniem domeny głównej.

Usuwanie domeny

doswiftly config domain remove <domena>

Usuwa Custom Hostname z Cloudflare i mapowanie z KV.

CI/CD z tokenem deploy

Wdrażanie można automatyzować w pipeline'ach CI/CD za pomocą tokenu deploy.

Konfiguracja

# Jednorazowe wygenerowanie tokenu
doswiftly auth token --deploy

# Ustawienie tokenu w CI/CD (np. GitHub Actions secret)
DOSWIFTLY_DEPLOY_TOKEN=<wygenerowany-token>

GitHub Actions

Automatyczne wdrażanie jest możliwe przez:

• Token deploy — ustawienie DOSWIFTLY_DEPLOY_TOKEN jako secret
• GitHub webhooks — po połączeniu konta (doswiftly auth github) push do main triggeruje produkcyjne wdrożenie, a otwarcie PR triggeruje preview
• Automatyczny setup workflow — po połączeniu repozytorium w panelu admina, platforma automatycznie generuje i pushuje deploy.yml do repozytorium oraz ustawia sekrety GitHub Actions. Nie edytuj tego pliku ręcznie — gdy generator workflow się zmienia, panel zgłasza dostępną aktualizację i plik jest podmieniany na nową wersję (ręczne zmiany zostaną nadpisane)

Wygenerowany workflow wstrzykuje do builda zmienne publiczne (inlinowane przez Next.js):

Kontrakt jest kanoniczny i niezależny od frameworka — zmienne DOSWIFTLY_* są dostępne po stronie serwera w każdym buildzie. Aliasy NEXT_PUBLIC_* mają te same wartości (wskazują te same sekrety) i istnieją po to, by Next.js — domyślny framework platformy — inlinował je do bundla przeglądarki:

Kanon (każdy framework)	Alias Next.js (inline do klienta)	Wartość	Zastosowanie
DOSWIFTLY_API_URL	NEXT_PUBLIC_API_URL	sekret repo (ustawiany przez platformę)	adres API
DOSWIFTLY_SHOP_SLUG	NEXT_PUBLIC_SHOP_SLUG	sekret repo (ustawiany przez platformę)	identyfikacja sklepu
DOSWIFTLY_DEPLOYMENT_COMMIT	NEXT_PUBLIC_DEPLOYMENT_COMMIT	SHA wdrażanego commita	identyfikacja własnego buildu — np. tag wersji w monitoringu błędów albo porównanie z nagłówkiem odpowiedzi X-Deployment-Version (v{timestamp}-{commitShort}), żeby wykryć, że użytkownik korzysta ze starszego buildu

Inne frameworki

Jeśli Twój projekt nie używa Next.js (pipeline wspiera też m.in. Nuxt, Astro, SvelteKit, Remix), po stronie serwera czytaj kanoniczną DOSWIFTLY_DEPLOYMENT_COMMIT. Aby wartość trafiła do kodu klienta, zmapuj ją w konfiguracji buildu zgodnie z konwencją publicznych zmiennych Twojego frameworka (np. PUBLIC_*, NUXT_PUBLIC_*, VITE_*).

Zmienne środowiskowe na produkcji

Przed wdrożeniem upewnij się, że zmienne środowiskowe są poprawnie skonfigurowane w profilu produkcyjnym:

# Przełącz na środowisko produkcyjne
doswiftly env use production

# Ustaw wymagane zmienne
doswiftly env set NEXT_PUBLIC_API_URL https://api.doswiftly.pl
doswiftly env set NEXT_PUBLIC_SHOP_SLUG moj-sklep

# Wdrożenie
doswiftly deploy run

uwaga

Zawsze sprawdź aktywne środowisko poleceniem doswiftly env list przed uruchomieniem doswiftly deploy run, aby uniknąć przypadkowego wdrożenia z konfiguracją deweloperską.

Typowy cykl pracy

1. Rozwój lokalny

doswiftly env use dev
doswiftly dev

2. Tworzenie podglądu dla code review

doswiftly env use staging
doswiftly preview create
# Udostępnij URL podglądu zespołowi

3. Wdrożenie na produkcję

doswiftly env use production
doswiftly verify          # Sprawdź konfigurację
doswiftly deploy run      # Buduj i wdrażaj
doswiftly deploy status   # Sprawdź wynik

4. Rollback w razie problemów

doswiftly deploy rollback
doswiftly deploy status   # Potwierdź wycofanie

Rozwiązywanie problemów

Wdrożenie kończy się stanem FAILED

1. Sprawdź logi: doswiftly deploy logs <deploymentId>
2. Uruchom diagnostykę: doswiftly doctor
3. Zweryfikuj zależności: doswiftly check
4. Sprawdź konfigurację: doswiftly verify

Pre-deployment check nie przechodzi

• Brak package.json — uruchom polecenie z katalogu głównego projektu
• Brak skryptu build — dodaj "build": "next build" do package.json
• Brak SDK — zainstaluj: pnpm add @doswiftly/storefront-sdk
• Brak zmiennych — ustaw: doswiftly env set NEXT_PUBLIC_API_URL <url>

Timeout pollingu (10 minut)

Jeśli wdrożenie przekroczy 10 minut, CLI zakończy polling. Sprawdź status ręcznie:

doswiftly deploy status

Wdrożenie może nadal trwać po stronie serwera.

---

Następne kroki

• Pełna referencja poleceń — wszystkie dostępne komendy
• SDK Overview — architektura SDK, hooki i stores
• Wdrażanie produkcyjne — szczegóły pipeline'u deploymentu