Migracja Shopify Scripts do Shopify Functions – Kompletny poradnik 2026
W związku z planowanym wyłączeniem Shopify Scripts (30 czerwca 2026) każde zaawansowane dostosowanie typu rabaty na poziomie koszyka, wysyłki czy płatności należy przenieść na nowe mechanizmy Shopify Functions i Checkout Extensibility. W tym artykule przedstawiamy kompletny przewodnik migracji z minimalnym ryzykiem przerw w działaniu sklepu. Omówimy nowe terminy (sunset skryptów i checkout.liquid), porównamy funkcjonalność rozwiązań, zaproponujemy szczegółową checklistę kroków migracji (z narzędziami, komendami CLI i przykładami kodu), strategie testów/CI/CD oraz plan awaryjny rollbacku. Na koniec zamieścimy szacunkowy harmonogram, typowe pułapki i FAQ.
May 27, 2026
|
Aleksander Olszewski
Kontekst: przejście ze skryptów na funkcje
Shopify oficjalnie zapowiedziało wycofanie klasycznych Shopify Scripts. Od 15 kwietnia 2026 nie będzie już możliwości edycji ani tworzenia nowych skryptów, a od 30 czerwca 2026 wszystkie istniejące skrypty przestaną działać. Skrypty były dostępne wyłącznie na planie Shopify Plus, a ich edytor (Script Editor) nie jest już oferowany w App Store. W praktyce każdy sklep Plus musi zatem do połowy 2026 roku zastąpić dotychczasowe skrypty nowym rozwiązaniem.
Nowa ścieżka to Shopify Functions oraz Checkout Extensibility. Functions to mechanizm pisania niestandardowej logiki (kompilowanej do WebAssembly) działający po stronie Shopify. Checkout Extensibility to z kolei platforma oparta na aplikacjach i rozszerzeniach (UI Extensions), która umożliwia m.in. modyfikacje procesu checkoutu bez modyfikowania motywu. Wprowadzono ją w 2022 roku i od tego czasu rozwijano. Warto też pamiętać, że od 13 sierpnia 2024 Shopify wyłączy wsparcie dla tradycyjnego checkout.liquid (początkowo na stronach informacji o przesyłce i płatności), a od 28 sierpnia 2025 również na stronach potwierdzenia zamówienia. Oznacza to, że wszelkie customizacje checkoutu muszą być realizowane aplikacyjnie – przez Checkout UI Extensions lub Shopify Functions (np. w celu tworzenia rabatów, dodatków przy zamówieniu itp.). Nowe funkcjonalności bazują głównie na GraphQL (np. za pomocą Shopify Admin API), podczas gdy starsze REST API i skrypty stają się przestarzałe. Migracja na Functions daje zatem większą skalowalność, wydajność i długoterminowe wsparcie, ale wymaga starannego przygotowania.
Porównanie: Shopify Scripts vs Shopify Functions
Poniższa tabela zestawia najważniejsze różnice między dotychczasowymi skryptami a nowymi funkcjami Shopify:
Shopify Functions działają w oparciu o GraphQL – definiujesz zapytanie (input_query w pliku run.graphql), które pobiera dane potrzebne Twojej funkcji. Następnie kod w Rust/TS przetwarza input JSON i zwraca deklaratywną odpowiedź . Warto też zauważyć, że funkcje wspierają konfigurację przez shop admin (metafields) i przyjazne UI (a skrypty wymagały kodu). Dzięki temu można łatwiej integrować logikę w aplikacjach i szybciej reagować na zmiany.
Krok 1: Audyt istniejących skryptów (raport dostosowań)
- Uzyskaj raport dostosowań – w Shopify Admin (Apps > Script Editor) znajdziesz Raport dostosowań Shopify Scripts, który automatycznie skanuje Twój sklep i wyświetla wszystkie aktywne skrypty (linia, wysyłka, płatności). Raport pokazuje nazwę, opis i źródło każdego skryptu oraz linki do odpowiadających mu rekomendowanych funkcji lub aplikacji. Shopify zaleca użycie tego raportu do planowania migracji.
- Przegląd skryptów – otwórz każdy znaleziony skrypt, zrozum jego logikę (warunki, rabaty, walidacje) i oceń, czy jest nadal potrzebny. Jeśli jakiś skrypt dotyczył już nieistniejącej promocji lub funkcji, można go zignorować. Skoncentruj się na tym, co musisz zachować: np. rabaty przy zakupie określonych produktów, darmowa wysyłka powyżej progu, przepinanie metod płatności itp. Niektóre funkcje mogą być odwzorowane przez gotowe aplikacje (więcej poniżej).
- Sporządź listę migracji – dla każdego skryptu zanotuj jego typ (line item, shipping, payment) i cel biznesowy. Na tej podstawie określ, które z nich wymagają migracji do funkcji, a które można zastąpić istniejącymi integracjami (np. standardowymi regułami rabatowymi Shopify lub aplikacją zewnętrzną). Podziel skrypty na: do odtworzenia i do zignorowania.
Krok 2: Wybór aplikacji lub własnej funkcji
Przejrzawszy skrypty, zastanów się nad opcjami odtworzenia:
- Gotowe aplikacje z funkcjami: Shopify App Store oferuje już wiele aplikacji „built on Shopify Functions” realizujących różne potrzeby (zwłaszcza promocyjne). Na przykład w kategorii „Discount Apps built on Shopify Functions” znajdziemy dziesiątki rozwiązań do rabatów, bundle’y i upselli (np. BOGOS: Free Gift Bundle, Kite Discount, Regios Automatic Discounts, Free Shipping Discounts – SC itd.). Przejrzyj App Store pod kątem aplikacji odpowiadających Twoim skryptom – instalacja gotowej aplikacji może być najszybszym rozwiązaniem. Aplikacje takie działają na każdym planie Shopify (public apps) i nie wymagają kodowania. Warto też zapoznać się z oficjalnymi zaleceniami Shopify: strona raportu dostosowań linkuje często do powiązanych aplikacji Functions.
- Budowa własnej funkcji: Jeśli nie ma pasującej aplikacji lub potrzebujesz niestandardowej logiki, trzeba stworzyć własne Shopify Function. To wymaga utworzenia aplikacji typu custom app w panelu Partnera (z obsługą Shopify App Bridge – uwaga: aplikacje funkcji muszą być tworzone w Shopify Partner Dashboard; aplikacje tworzone bezpośrednio w adminie sklepu nie wspierają funkcji). W praktyce zakładasz aplikację w Shopify Partner, generujesz z niej rozszerzenie typu „Function” (za pomocą Shopify CLI), a następnie piszesz logikę w wybranym języku (zwykle Rust lub TypeScript). W kolejnym kroku aplikację trzeba zdeployować i zainstalować w swoim sklepie.
Krok 3: Tworzenie funkcji – środowisko i kod
A. Utworzenie projektu: Zainstaluj najnowszą wersję Shopify CLI (3.0+) i zaloguj się (shopify login). Następnie w katalogu projektu użyj odpowiedniej komendy, np.:
pgsqlKopiuj
shopify app create extension --type=FUNCTION --name=my-discount-function
Wybierz język (Rust lub JavaScript/TypeScript). CLI wygeneruje strukturę folderów (np. extensions/my-discount-function) oraz szablon shopify.extension.toml z opisem rozszerzenia. W pliku TOML definiujesz m.in. target (rodzaj funkcji: np. product_discount, shipping_discount) i ścieżki do plików zapytań GraphQL (input_query). Domyślnie utworzy się run.graphql – zapytanie GraphQL określające, jakie dane ma otrzymać funkcja (np. cart { lines { quantity, merchandise { ... } } }). Możesz edytować run.graphql, aby pobrać tylko potrzebne pola, a CRM CLI automatycznie zaktualizuje strukturę JSON wejściową testu (input.json).
B. Implementacja logiki: W wygenerowanym pliku źródłowym (src/index.ts lub src/lib.rs) zaimplementuj swoją logikę. Przy tej okazji:
- Skorzystaj z generowanych typów:
shopify_function(Rust) lubFunctions API(TS) generuje struktury dla obiektów wejściowych i wyjściowych na podstawie zapytania GraphQL, dzięki czemu masz pełne typy. - Przykładowy kod: Poniżej fragment starego skryptu (Ruby) oraz odpowiadająca mu funkcja (TypeScript):
ruby
# Przykład starego skryptu "line item"
customer = Input.cart.customer
Input.cart.line_items.each do |line_item|
product = line_item.variant.product
next if product.gift_card?
# Zastosuj zniżkę 9 zł na każdy nie-giftcard
line_item.change_line_price(line_item.line_price - Money.new(cents: 900),
message: customer.total_spent)
end
Output.cart = Input.cart
ts
// Odpowiednik w Shopify Function (TypeScript, uproszczony)
export default (input) => {
// Pobrać konfigurację - np. procent znizki lub wartość z catalog/metafieldów
const discountCents = 900;
const targetItems = input.cart.lines.filter(line => !line.merchandise.giftCard);
let newCartLines = targetItems.map(line => {
const newPrice = line.cost.amount - discountCents;
return {
...line,
discountedAmount: { amount: discountCents, percentage: (discountCents/line.cost.amount)*100 },
newTotal: { amount: newPrice, currencyCode: line.cost.currencyCode }
};
});
return {
discounts: newCartLines.map(line => ({
cartLineId: line.id,
price: { amount: -discountCents, currencyCode: line.cost.currencyCode }
})),
discountApplicationStrategy: "First"
};
}
- W powyższym kodzie widać różnice: skrypt Ruby bezpośrednio manipulował ceną linii, natomiast funkcja zwraca strukturę z operacjami (discounts, discountApplicationStrategy), zgodnie ze schematem Shopify Functions API. Struktury wejściowe/wyjściowe są zdefiniowane przez GraphQL – dzięki temu funkcja zwraca gotowe operacje do wykonania przez platformę.
- Komendy pomocnicze: Podczas developmentu użyj
shopify extension serveaby uruchomić lokalny podgląd i testować zmiany „na żywo”. Możesz także użyćshopify app function schemaishopify app function typegen(lub odpowiednich npm/CLI scriptów) aby zaktualizować schemat GraphQL i typy po każdej zmianie w kodzie lub zapytaniu. Klasashopify_functionw Rust generuje rodzaje i testy na bazie pliku.json.
C. Testy lokalne: Wykonaj testy jednostkowe funkji. W Rust możesz użyć funkcji run_function_with_input (z shopify_function_macro) do testów na przykładzie przykładowych JSON-ów. W TS możesz wykorzystać wygenerowaną strukturę wyjściową i napisać testy integracyjne (np. Jest). Upewnij się, że logika funkcji działa zgodnie z oczekiwaniami dla różnych scenariuszy (różna liczba produktów, waluty, tagi klientów itp.). Możesz też tymczasowo korzystać z aplikacji GraphiQL (lub innego klienta GraphQL) po zdeployowaniu aplikacji, aby wywołać mutacje np. functionAppCreate i ręcznie sprawdzić, czy funkcja działa w sklepie (jak w poradniku Tomasza Blancharda).
Krok 4: CI/CD i automatyzacja
Aby zapewnić spójność i łatwiejszą współpracę zespołową, zbuduj CI/CD dla swojego projektu Functions:
- Kontrola wersji: Przechowuj kod funkcji w repozytorium (np. GitHub), uwzględniając pliki źródłowe i pliki konfiguracyjne CLI (
shopify.extension.toml,run.graphqlitp.), ale bez plików generowanych (.output.graphqlitp. można dodać do.gitignore). - Shopify CLI w pipeline: Użyj oficjalnego GitHub Action
shopify/shopify-cli-actionlub konfiguruj manualnie środowisko w CI (Node.js, Rust, Shopify CLI). W akcji CI ustaw zmienne środowiskowe (np.SHOPIFY_CLI_AUTH_TOKEN,SHOPitp.), żeby CLI mógł uwierzytelnić się do Twojego sklepu Partners lub dev store. W krokach wykonujshopify extension buildishopify app config push(lubshopify deploy) aby zbudować paczkę WASM i wdrożyć zmiany konfiguracji. W razie użycia funkcji typu discount, testuj również odpowiednie mutacje GraphQL (np.discountAutomaticAppCreate) w automatyczny sposób – można skrypty końcowe wykonać np. z użyciemshopify api runlub GraphQL. - Testy regresyjne: Integruj testy automatyczne. Po deployu do środowiska testowego (dev store) wypuszczaj zestaw scenariuszy (np. testy Selenium lub scripty interakcji z API), aby upewnić się, że zachowania biznesowe są poprawne (np. sumy rabatów). Gdy testy zakończą się sukcesem, workflow może być zatwierdzany automatycznie. Dzięki temu przed każdym wdrożeniem będziesz miał pewność, że zmiany nie łamią nic krytycznego.
Krok 5: Wdrożenie i przełączenie na produkcji
- Deploy aplikacji: Po zakończonym testowaniu wypchnij aplikację do Shopify (CLI:
shopify deploy). Następnie w Partner Dashboard udostępnij aplikację (np. Custom distribution – dodaj link instalacyjny do swojego sklepu). Zainstaluj aplikację w docelowym sklepie Plus. - Aktywacja funkcji: Po instalacji funkcji w sklepie, skonfiguruj ją w panelu admina. W zależności od celu funkcji, może to polegać na aktywacji określonego typu rabatu lub włączeniu walidacji. Przykładowo, aby stworzyć zniżkę automatyczną z funkcją, w GraphiQL wklej odpowiednią mutację (analogiczną do [35†L355-L364]) lub skorzystaj z interfejsu admina, jeśli dostępny (Shopify udostępnia w adminie sekcje konfiguracyjne dla funkcji).
- Testy w środowisku produkcyjnym: Przed wyłączeniem skryptów upewnij się, że funkcje działają jak oczekiwano na produkcji. Przeprowadź testy “przed i po” (np. złóż próbne zamówienia, sprawdź różne scenariusze rabatowe). Współpracuj z zespołem QA i klientem, aby potwierdzić poprawność działania.
- Wyłączenie starych skryptów: Gdy nowa funkcja jest stabilna, dezaktywuj odpowiadające jej stare skrypty w edytorze (lub całkowicie usuń). Ważne: przez cały czas migracji skrypty i funkcje mogą działać równocześnie – Shopify pozwala na koegzystencję obu systemów. Dzięki temu można bezpiecznie wyłączyć stary skrypt dopiero po weryfikacji, że funkcja go poprawnie zastępuje.
Strategie testów i rollbacku
- Migracja „bez przestoju”: Planuj wdrożenie podczas niższego ruchu (noc, weekend) i najszybciej, jak to możliwe po pełnym przetestowaniu. Dzięki możliwości równoległej pracy skryptów i funkcji oraz szybkiemu wyłączaniu skryptów w adminie, przerwy w działaniu sklepu mogą być minimalne lub zerowe.
- Obsługa błędów: Przygotuj plan awaryjny: w razie problemu natychmiast wyłącz nowo wprowadzoną funkcję (w panelu admina aplikacji) i/lub przywróć działanie starego skryptu (ponieważ nie został usunięty, jedynie wyłączony). Możesz też zastosować feature-flag: niektóre firmy tworzą dodatkową metodykę, gdzie funkcja przez pewien czas działa warunkowo (np. dopiero po zastosowaniu określonego znacznika).
- Ciagłość biznesu: Monitoruj metryki sklepu (obroty, konwersje) po migracji i porównaj ze stanem poprzednim. Przygotuj team support na szybkie reakcje (w tym obsługę zgłoszeń klienta lub alertów systemowych). Dzięki temu ryzyko błędów można zminimalizować.
Typowe pułapki i FAQ
- Konfiguracja przez klienta: W przeciwieństwie do skryptów, funkcje nie są edytowalne przez merchantów w adminie. Aby umożliwić klientowi zmianę parametrów (np. wartości progów rabatowych), można użyć metafields sklepu lub własnego UI. Istnieją sposoby obejścia – np. trzymanie konfiguracji w shop-level metafield i odczytywanie jej w funkcji. To rozwiązanie pozwala na modyfikację ustawień bez potrzeby deployu kodu.
- Limit zapytań GraphQL: Funkcja może pobierać tylko ograniczone dane (limit złożoności zapytania ~30). Upewnij się, że
run.graphqlzawiera tylko niezbędne pola. Dodatkowe dane można uzyskać przez app-owned metafields, input variables lub osobne zapytania w funkcji (funkcja ma też możliwość zewnętrznego fetchowania przez ustawienie[[targeting]] ... fetch). - Zależności środowiskowe: Skrypty działały na stanach checkoutu wprost (np. mogą pobierać lokalizację sklepu). Funkcje uruchamiane są w izolowanym serwerze, więc nie mają dostępu do stanu sesji poza tym, co znajduje się w
run.graphql. Jeśli potrzebujesz dodatkowych danych, rozważ dodanie ich do zapytania lub użycie metafieldów. - Błędy wersjonowania: Shopify Functions korzystają z wersjonowania aplikacji. Upewnij się, że w
shopify.extension.tomlmasz ustawione odpowiednieapi_version(najlepiej najnowszą wspieraną), żeby uniknąć nagłych zmian w API. Śledź changelogi funkcji Shopify (co kwartał są nowe wersje) i planuj aktualizacje. - Dostęp w niskich planach: Publiczne aplikacje z funkcjami działają na wszystkich planach, ale niestandardowe (custom) aplikacje z funkcjami wymagają Shopify Plus. Jeśli klient nie jest na Plus, trzeba korzystać z gotowych publicznych app lub negocjować upgrade.
- Checkout Extensibility a stare skrypty: Jeśli używałeś
checkout.liquid(do wstawek HTML/JS w checkout), pamiętaj, że od poł. 2024 nie będzie już wspierany. Wszystkie modyfikacje checkoutu muszą zostać przeniesione na Checkout UI Extensions (np. do thank-you page) lub logikę Functions (np. line item discounts działają na etapie koszyka/checkout).
Szacunkowy harmonogram i estymacja ryzyka
- Czas migracji: Prosty sklep z jednym skryptem (np. prosty rabat na całość) można migrować w ciągu kilku dni – głównie pisanie funkcji i testy. Średnio jednak całkowita migracja (audyt, development, test, deploy) może zająć kilka tygodni dla standardowego sklepu z kilkoma skryptami. Bardziej złożone scenariusze (wiele różnych skryptów – rabaty, wysyłka, walidacje – o skomplikowanej logice) mogą wymagać 1–3 miesięcy pracy (zwłaszcza jeśli trzeba zoptymalizować i przetestować niestandardową logikę funkcji).
- Ryzyka: Największe zagrożenia to błędne odtworzenie logiki (np. różnice w zaokrągleniach, nieobsłużone przypadki brzegowe) oraz nieuwzględnienie nowych limitów API. Aby je zminimalizować, poświęć dodatkowy czas na weryfikację matematyki rabatów, uwzględnij różne scenariusze walutowe/podatkowe oraz przetestuj funkcje przy dużej liczbie linii (Shopify zaleca Rust, gdyż JS może spowolnić przy bardzo dużych koszykach). Ponadto, przygotuj plan komunikacji z klientem: poinformuj go o nadchodzących zmianach, terminach i możliwym niedługotrwałym ryzyku podczas przejścia.
Potrzebujesz pomocy przy migracji? Skontaktuj się z nami! Attomy to certyfikowana agencja Shopify Plus i Odoo. Pomożemy przeprowadzić bezpieczną migrację Twoich skryptów do Shopify Functions i zapewnić ciągłość działania sklepu.
