Zmienne środowiskowe

Platforma dostarcza każdemu buildowi storefrontu ustalony zestaw zmiennych. Kontrakt jest kanoniczny i niezależny od frameworka — aliasy takie jak NEXT_PUBLIC_* niosą te same wartości i istnieją po to, żeby framework mógł wstawić je do bundla przeglądarki.

Nowe zmienne czytaj i zapisuj zawsze pod nazwą kanoniczną. Alias traktuj jako zgodność wsteczną.

Kontrakt podstawowy

Kanon (każdy framework)	Alias Next.js	Wartość	Skąd pochodzi
DOSWIFTLY_API_URL	NEXT_PUBLIC_API_URL	Adres API	Sekret repozytorium, doswiftly env generate, doswiftly init (.env.local), doswiftly dev
DOSWIFTLY_SHOP_SLUG	NEXT_PUBLIC_SHOP_SLUG	Identyfikator sklepu	jw.
DOSWIFTLY_DEPLOYMENT_COMMIT	NEXT_PUBLIC_DEPLOYMENT_COMMIT	SHA wdrażanego commita	Wyłącznie pipeline CI

DOSWIFTLY_DEPLOYMENT_COMMIT możesz porównać z nagłówkiem odpowiedzi X-Deployment-Version, żeby sprawdzić, która wersja jest aktualnie serwowana.

Dwa adresy API, dwie role

Adres API pełni dwie różne funkcje i w niektórych konfiguracjach są to różne hosty:

• DOSWIFTLY_API_URL — używany przez narzędzie wiersza poleceń przy wdrożeniu. Zawsze wskazuje host platformy.
• NEXT_PUBLIC_API_URL (i pozostałe aliasy publiczne) — używany przez działający sklep do zapytań Storefront GraphQL. Może wskazywać host platformy albo osobny adres przypisany do Twojej domeny.

Domyślnie oba niosą ten sam adres. Jeśli Twój sklep ma przypisany własny host danych, rozdzielenie następuje automatycznie przy generowaniu konfiguracji wdrożenia — nie ustawiaj DOSWIFTLY_API_URL na adres swojej domeny, bo obsługuje ona wyłącznie ruch sklepowy, a polecenia wdrożeniowe zwrócą wtedy błąd 404.

Zachowanie w poszczególnych warstwach

• Budowanie (doswiftly deploy) — nazwy kanoniczne są odwzorowywane na konwencję publicznych zmiennych wykrytego frameworka: NEXT_PUBLIC_*, PUBLIC_* (Astro, SvelteKit), NUXT_PUBLIC_*, VITE_* (Remix na Vite). Kod kliencki czyta je bez dodatkowej konfiguracji, a wartości już ustawione nigdy nie są nadpisywane.
• Walidacja (deploy, check, verify) — wymaganie jest spełnione, gdy obecna jest nazwa kanoniczna albo alias.
• Praca lokalna — doswiftly env generate zapisuje obie formy do .env.local na podstawie aktywnego profilu.

Zmienne własne sklepu — zarządzane z panelu

Poza kontraktem platformy sklep może mieć własne zmienne (klucze analityki, tokeny zewnętrznych API, flagi konfiguracyjne). Zarządza się nimi w panelu administracyjnym: Storefront → Ustawienia → Zmienne środowiskowe (sekcja widoczna w trybie własnego storefrontu).

Jak to działa:

• Zapis działa od razu — wartości trafiają prosto do środowiska działającego sklepu (odczytasz je w kodzie serwerowym przez process.env.NAZWA), bez przebudowy.
• Build też je widzi — doswiftly deploy pobiera aktualny zestaw przed budowaniem, więc zmienne z publicznym przedrostkiem (NEXT_PUBLIC_*, PUBLIC_*, NUXT_PUBLIC_*, VITE_*) zostaną wtopione w bundel przeglądarki przy najbliższym wdrożeniu. Panel przypomina o tym i pozwala uruchomić wdrożenie jednym przyciskiem.
• Wartości ukryte są maskowane w panelu i w logach GitHub Actions. Pamiętaj: wartość użyta w kodzie działającym w przeglądarce będzie tam widoczna niezależnie od ukrycia — ukrycie chroni podgląd, nie bundel.
• Nazwy zarezerwowane platformy (DOSWIFTLY_* i aliasy kontraktu z tabeli powyżej) są odrzucane przy zapisie — wartości kontraktu zawsze pochodzą z platformy i nigdy nie są nadpisywane wartością sklepu.
• Sekcja [vars] we własnym wrangler.toml nadal działa dla jawnych wartości, ale ma najniższy priorytet i wymaga wdrożenia; dla Next.js plik jest generowany przy buildzie, więc [vars] z repozytorium nie są przenoszone. Zalecany sposób zarządzania zmiennymi to panel.

Zmienne dostępne tylko na czas budowania

Build renderuje wiele stron naraz i wysyła zapytania seriami z jednego adresu — inaczej niż przeglądarka kupującego. Te zmienne pozwalają nim sterować i celowo nie mają aliasu publicznego: nie mogą trafić do bundla przeglądarki.

Zmienna	Do czego służy
DOSWIFTLY_BUILD	Oznacza proces budowania — SDK włącza wtedy rozkładanie zapytań w czasie
DOSWIFTLY_BUILD_CONCURRENCY	Sufit liczby równoczesnych żądań
DOSWIFTLY_BUILD_MIN_INTERVAL_MS	Minimalny odstęp między startami żądań
DOSWIFTLY_BUILD_API_URL	Adres, z którego build pobiera dane

Nie dodawaj publicznego aliasu do zmiennych budowania

Alias publiczny zostałby wtopiony w bundel przeglądarki, przez co kupujący zacząłby wysyłać zapytania pod adres przeznaczony dla builda. Te zmienne mają działać wyłącznie wewnątrz procesu budowania.

Powiązane

• Komendy CLI — pełna referencja poleceń
• Konfiguracja i profile — skąd biorą się wartości przy pracy lokalnej