Vue 3: Composition API kontra Options API w dużych bibliotekach komponentów

Dlaczego ten wybór ma znaczenie w dużych bibliotekach komponentów administracyjnych

Duża biblioteka komponentów w aplikacji administracyjnej to nie strona marketingowa z kilkoma przyciskami. To dziesiątki (albo setki) bloków budulcowych powtarzających się na ekranach: tabele z sortowaniem i akcjami zbiorczymi, panele filtrów, formularze z regułami walidacji, wysuwane panele i modalne okna, przepływy potwierdzeń oraz małe narzędzia jak wybieracze dat i strażnicy uprawnień.

Ponieważ te wzorce pojawiają się wszędzie, zespoły często kopiują i modyfikują kod, żeby dotrzymać terminów. Jednej tabeli dodaje się niestandardowy pasek filtrów, innej – trochę inny; wkrótce masz pięć „prawie takich samych” wersji. Wtedy pytanie Composition API vs Options API przestaje być kwestią preferencji, a zaczyna wpływać na zdrowie całej biblioteki.

Najpierw zwykle pęka spójność. UI działa, ale zachowanie dryfuje: modal zamyka się na Escape w jednym miejscu, a w innym nie; to samo pole formularza waliduje przy blur w jednym widoku, a przy submit w innym. Potem spada prędkość pracy, bo każda zmiana wymaga szukania po niemal duplikatach. Na koniec spada pewność siebie: ludzie unikają refaktorów, bo nie potrafią przewidzieć, co zostanie dotknięte.

Trzy praktyczne decyzje mają największe znaczenie w bibliotece współdzielonej:

• Ponowne użycie kodu: jak opakowujesz wspólną logikę bez splątanych zależności.
• Testowanie: jak łatwo weryfikować zachowanie bez kruchych testów zależnych od UI.
• Onboarding: jak szybko nowy współpracownik może przeczytać komponent i bezpiecznie go zmienić.

Prosty przykład: w administracji masz 20 stron list i produkt prosi o funkcję „zapisane filtry”. Jeśli logika tabeli, filtrów i synchronizacji z URL jest rozrzucona i niespójna, wypuścisz to albo wolno, albo z błędami. Styl API, który wybierzesz, kształtuje, czy ta logika żyje w jednym, wielokrotnego użytku miejscu, jak jasno jest powiązana z każdym ekranem i jak łatwo ktoś nowy może ją rozszerzyć.

Jeśli budujesz admin‑aplikacje w Vue 3 (w tym zespoły używające Vue 3 wewnątrz platform jak AppMaster do warstwy UI webowej), podjęcie tej decyzji wcześnie może zaoszczędzić miesięcy prac konserwacyjnych.

Jak Options i Composition różnią się w codziennym kodzie

Najszybszy sposób, żeby poczuć różnicę, to otworzyć duży komponent administracyjny i zapytać: „Gdzie zmieniam zachowanie dla tej funkcji?”. W bibliotece komponentów to pytanie pojawia się codziennie.

W Options API kod jest pogrupowany według typów: data dla stanu, methods dla akcji, computed dla wartości pochodnych i watch dla efektów ubocznych. Taka struktura jest łatwa do przeglądania, gdy komponent jest mały. W dużej tabeli czy komponencie formularza logika jednej funkcji (np. akcje zbiorcze czy walidacja pola) często rozkłada się na kilka bloków. Możesz utrzymać porządek, ale wymaga to dyscypliny i spójnych nazw, żeby uniknąć przeskakiwania po pliku.

W Composition API kod zwykle grupuje się według funkcji. Definiujesz powiązany stan, wartości pochodne, efekty uboczne i pomocniki razem i możesz wyciągać powtarzaną logikę do komposabli. W bibliotece administracyjnej często to odpowiada sposobowi myślenia: „wszystko o filtrowaniu jest tutaj”, „wszystko o zaznaczaniu wierszy jest tutaj”. To też zmniejsza duplikację między podobnymi komponentami, np. ponowne użycie usePagination we wszystkich tabelach.

Duża, codzienna różnica to sposób pokazywania zależności.

• Options API może być bardziej niejawne: metoda może polegać na this.user, this.filters i this.loading, czego dowiadujesz się dopiero czytając wnętrze metody.
• Composition API jest zwykle bardziej jawne: gdy funkcja domyka się nad filters i loading, widzisz te zmienne zdefiniowane obok i możesz je przekazywać do helperów, gdy trzeba.

Minus jest taki, że Composition API może stać się hałaśliwe, jeśli wszystko zostanie wyrzucone do jednego setup() bez struktury.

Praktyczna zasada:

• Wybierz Options API, gdy komponenty są głównie prezentacyjne i mają niewiele logiki.
• Wybierz Composition API, gdy komponenty mają wiele funkcji i zasady współdzielone w bibliotece.
• Jeśli wybierzesz Composition API, uzgodnij prosty układ grupujący kod według funkcji (nie „wszystkie refy najpierw”).
• Jeśli wybierzesz Options API, egzekwuj nazewnictwo i trzymaj powiązaną logikę blisko siebie z krótkimi komentarzami i spójnymi nazwami metod.

Oba mogą działać. Kluczowe jest wybranie stylu organizacji, który sprawia, że następna zmiana jest oczywista, a nie wyszukana.

Ponowne użycie kodu: co skaluje się czysto, a co staje się bałaganem

W aplikacjach administracyjnych reuse to nie luksus. Powtarzasz te same zachowania na dziesiątkach ekranów, a drobne niespójności zamieniają się w błędy i zgłoszenia do wsparcia.

Większość potrzeb ponownego użycia mieści się w kilku powtarzalnych kategoriach: sortowanie/filtrowanie/paginacja zgodna z backendem, walidacja formularzy i mapowanie błędów, sprawdzanie uprawnień i blokowanie UI, synchronizacja zapytań (parametry URL, zapisane widoki, domyślne filtry) oraz akcje zbiorcze z regułami zaznaczania w tabeli.

Reuse w Options API: potężne, ale łatwo ukryć złożoność

W Options API reuse często zaczyna się od mixinów, extends lub pluginów.

Mixiny są szybkie, ale słabo skalują, bo ukrywają, skąd pochodzi metoda lub wartość obliczana. Dwa mixiny mogą cicho kolidować na tę samą nazwę metody i wtedy debugowanie zachowania odbywa się poza plikiem komponentu.

extends może wydawać się czyściejsze niż mixiny, ale nadal tworzy zagadki dziedziczenia, gdzie musisz czytać wiele plików, żeby zrozumieć, co komponent robi. Pluginy sprawdzają się dla spraw na poziomie aplikacji (globalne dyrektywy, współdzielone serwisy), ale nie są dobrym miejscem dla reguł biznesowych, które różnią się między ekranami.

Moment, kiedy robi się bałagan, zwykle nadchodzi, gdy reuse staje się niejawne. Nowi współpracownicy nie potrafią odpowiedzieć „skąd pochodzą te dane?” bez przeszukania całego repozytorium.

Reuse w Composition API: komposable, które pozostają jawne

Reuse w Composition API zwykle buduje się wokół komposabli: małych funkcji zwracających refy, wartości obliczone i handlery. Duży plus jest taki, że reuse staje się widoczny blisko góry komponentu i możesz przekazywać parametry zamiast polegać na ukrytym kontekście komponentu.

Na przykład usePagination może przyjmować domyślne wartości i zwracać zmiany w spójnym kształcie, a usePermissions może przyjmować bieżącą rolę i nazwę funkcji. Wtedy wybór staje się mniej o składni, a bardziej o tym, czy twoja biblioteka woli jawne wiązanie zamiast ukrytego dziedziczenia.

Aby reuse pozostało przewidywalne, traktuj każdą jednostkę jak małe API: daj jej jasną nazwę, zdefiniuj wejścia i wyjścia oraz jedną odpowiedzialność. Jeśli composable zaczyna obsługiwać paginację, cache, uprawnienia i powiadomienia, podziel go. Łatwiej później podmienić jedną część bez łamania reszty.

Budowanie wielokrotnego użytku formularzy i tabel bez bólu

W aplikacjach administracyjnych formularze i tabele to miejsca, gdzie biblioteka komponentów albo się opłaca, albo zamienia w labirynt. Oba API mogą działać. Różnica polega na tym, jak opakujesz wspólne zachowania, np. stan „brudny”, mapowanie błędów i przepływy submit, bez nadmiernego „uspecjalniania” każdego komponentu.

Dla wspólnej logiki formularza Options API zwykle kieruje cię w stronę mixinów lub współdzielonych helperów. Mixiny mogą wydawać się wygodne na początku, ale później trudno odpowiedzieć na podstawowe pytania: „Skąd pochodzi ten błąd pola?” albo „Dlaczego submit jest wyłączony?”

Composition API sprawia, że ten rodzaj reuse jest bardziej widoczny, bo możesz przenieść logikę do komposabli (np. useDirtyState, useFormErrors, useSubmitFlow) i dokładnie widzieć, co komponent formularza importuje. W dużej bibliotece ta jasność często ma większe znaczenie niż oszczędzenie kilku linii.

Praktyczny sposób, by utrzymać stabilne API komponentów, to traktować powierzchnię publiczną jako kontrakt: propsy, emity i sloty powinny rzadko się zmieniać, nawet jeśli przepisać wnętrze. Ten kontrakt wygląda tak samo w obu stylach, ale Composition API często ułatwia bezpieczne refaktory, bo możesz wymieniać pojedyncze composable bez dotykania API szablonu.

Wzorce, które zwykle pozostają sensowne, gdy biblioteka rośnie:

• Buduj komponenty bazowe robiące jedno zadanie dobrze (BaseInput, BaseSelect, BaseTable), a następnie komponuj je w komponenty funkcjonalne.
• Preferuj sloty dla elastyczności układu (obszar akcji, stany puste, renderowanie komórek) zamiast dodawania propów na każdy skrajny przypadek.
• Normalizuj zdarzenia wcześnie (np. update:modelValue, submit, rowClick), żeby aplikacje nie polegały na szczegółach wewnętrznych.
• Trzymaj walidację i formatowanie blisko inputów, ale reguły biznesowe poza nimi (w composablach lub komponentach rodzicach).

Nadabstrakcja to częsta pułapka. „Super formularz”, który obsługuje każdy typ pola, każdą regułę walidacji i każdy wariant układu, często staje się trudniejszy w użyciu niż zwykłe Vue. Dobra zasada: jeśli komponent bazowy potrzebuje więcej niż garść propów, by pokryć potrzeby wszystkich zespołów, prawdopodobnie to dwa komponenty.

Czasem duplikacja jest właściwym wyborem. Jeśli tylko jeden ekran potrzebuje dziwnego nagłówka tabeli z grupowaniem wielorzędowym, skopiuj mały fragment i trzymaj go lokalnie. Sprytne abstrakcje mają długi ogon utrzymaniowy, szczególnie gdy dołączają nowi współpracownicy i próbują zrozumieć różnicę między „normalnymi” komponentami a frameworkiem wewnątrz frameworka.

Jeśli decydujesz między Composition a Options dla dużej biblioteki formularzy i tabel, optymalizuj najpierw czytelność przepływu danych. Reuse jest świetny, ale nie wtedy, gdy ukrywa ścieżkę od akcji użytkownika do emitowanego zdarzenia.

Wpływ na testowanie: co łatwiej zweryfikować

W bibliotece komponentów testy zwykle dzielą się na trzy grupy: czysta logika (formatowanie, walidacja, filtrowanie), renderowanie (co się wyświetla dla danego stanu) i interakcje (kliknięcia, input, klawiatura, emity). Styl API zmienia, jak często możesz testować pierwszą grupę bez montowania pełnego komponentu.

Testy Options API zwykle wyglądają jak „zamontuj komponent, ustaw stan instancji, assercja DOM”. To działa, ale może zachęcać do większych testów, bo logika jest wymieszana w methods, computed, watch i hookach cyklu życia. Kiedy coś zawodzi, trzeba też rozstrzygać, czy to timing watchera, efekt cyklu życia, czy sama logika.

Options API często wydaje się prosty dla:

• Przepływów użytkownika zależnych od kolejności cyklu życia (fetch on mount, reset on route change)
• Zachowań napędzanych watchami (auto‑save, synchronizacja zapytań)
• Emisji zdarzeń z metod komponentu (save(), reset(), applyFilter())

Composition API przesuwa balans. Jeśli przeniesiesz logikę do composabli, możesz testować tę logikę jako zwykłe funkcje, z małymi wejściami i jasnymi wyjściami. To zmniejsza liczbę testów „zamontuj i kliknij”, które potrzebujesz, i lokalizuje awarie. Ułatwia też kontrolę zależności: zamiast mockować global, przekazujesz zależność (funkcję fetch, format daty czy checker uprawnień) do composable.

Konkretny przykład: wielokrotnie używana AdminTable z sortowaniem, paginacją i zaznaczonymi wierszami. W Composition API logika zaznaczania może żyć w useRowSelection() i być testowana bez renderowania tabeli w ogóle (toggle, clear, select all, zachowanie między stronami). Wtedy zostawia się mniejszy zestaw testów komponentowych, by upewnić się, że szablon poprawnie wiąże przyciski, checkboxy i emity.

Aby utrzymać testy małe i czytelne (bez względu na styl), zbuduj wyraźne uszczelnienie między logiką a UI:

• Umieszczaj reguły biznesowe w czystych funkcjach lub composablach, nie w watcherach.
• Trzymaj efekty uboczne (fetch, storage, timery) za wstrzykiwanymi zależnościami.
• Preferuj kilka skoncentrowanych testów integracyjnych na komponent, a nie jeden gigantyczny „wszystko” test.
• Nazewnictwo stanów i zdarzeń trzymaj spójne w całej bibliotece (ułatwia to konfigurację testów).
• Unikaj ukrytych sprzężeń (np. metoda A zależy od uruchomienia watchera B).

Jeśli celem jest styl, który poprawi stabilność testów, dąż do mniejszej liczby zachowań zależnych od cyklu życia i większej liczby izolowanych jednostek logiki, które można weryfikować bez DOM.

Onboarding nowych współpracowników: jak szybko stają się produktywni

W dużej bibliotece komponentów administracyjnych onboarding to mniej nauka Vue, a bardziej pomoc w znajdowaniu rzeczy, przestrzeganiu konwencji i poczuciu bezpieczeństwa przy wprowadzaniu zmian. Większość opóźnień wynika z trzech braków: nawigacji (gdzie jest logika?), konwencji (jak tu to robimy?) i pewności (jak zmienić to bez złamania pięciu ekranów?).

W Options API nowi zwykle ruszają szybciej pierwszego dnia, bo struktura jest znajoma: props, data, computed, methods, watchers. Minusem jest to, że rzeczywiste zachowanie często jest rozproszone. Jedna funkcja jak „filtrowanie po stronie serwera” może być podzielona między watch, computed i dwie metody plus mixin. Ludzie czytają każdy blok, ale spędzają czas na zszywaniu tej historii.

W Composition API wygrana w onboardingu polega na tym, że powiązana logika może siedzieć razem: stan, efekty uboczne i helpery w jednym miejscu. Kosztem jest konieczność poznania konwencji composabli. Nowi muszą zrozumieć wzorce jak useTableState() i jak reaktywne wartości przepływają przez kilka composabli. Bez jasnych granic może to przypominać skakanie między plikami bez mapy.

Kilka konwencji rozwiązuje większość pytań, niezależnie od stylu:

• Utrzymuj przewidywalną strukturę: components/, composables/, types/, tests/.
• Wybierz schemat nazewnictwa i trzymaj się go (np. useX, XTable, XForm).
• Dodaj krótkie docbloki: co robi komponent, kluczowe propsy i główne eventy.
• Zdefiniuj jedną regułę „escape hatch” (kiedy wolno dodać nowy composable lub helper).
• Trzymaj mały „złoty” komponent pokazujący preferowany wzorzec.

Przykład: jeśli zespół generuje panel administracyjny Vue 3, a potem go dopasowuje (np. aplikacja webowa zbudowana na AppMaster i rozszerzana przez deweloperów), onboarding znacznie poprawia się, gdy jest jedno oczywiste miejsce do dostosowania zachowania tabeli (sortowanie, filtry, paginacja) i jedno miejsce do dostosowania powiązań UI (sloty, renderer kolumn, akcje wierszy). Ta jasność ma większe znaczenie niż wybrane API.

Krok po kroku: jak wybrać styl i wprowadzić go bezpiecznie

Dla dużej biblioteki UI administracyjnej najbezpieczniej jest zacząć od jednego dobrze ograniczonego elementu i potraktować go jako pilota, nie jako pełen rewrite.

Wybierz moduł o jasnym zachowaniu i wysokim współużytkowaniu, jak filtrowanie tabeli czy walidacja formularza. Zanim dotkniesz kodu, zapisz co robi dziś: wejścia (propsy, parametry zapytania, akcje użytkownika), wyjścia (emity, zmiany URL) i przypadki brzegowe (pusty stan, reset, błędy serwera).

Następnie ustal granice. Zdecyduj, co musi pozostać wewnątrz komponentu (renderowanie, zdarzenia DOM, dostępność), a co można przenieść do kodu współdzielonego (parsowanie filtrów, debouncing, budowanie parametrów API, stan domyślny). Tu wiele bibliotek się myli: jeśli przeniesiesz decyzje UI do współdzielonego kodu, utrudnisz ponowne użycie.

Praktyczny plan wdrożenia:

• Wybierz komponent pokazujący wzorzec i używany przez wiele ekranów.
• Wyodrębnij jedną wspólną jednostkę (composable lub zwykły helper) z małym, jawnym API.
• Najpierw napisz skupiony test dla tej jednostki, oparty na realnych scenariuszach administracyjnych.
• Przefaktoryzuj wybrany komponent end‑to‑end używając nowej jednostki.
• Zastosuj ten sam wzorzec do kolejnego komponentu, by potwierdzić skalowalność.

Trzymaj wspólne API nudne i oczywiste. Na przykład useTableFilters() może przyjmować początkowe filtry i udostępniać filters, apply(), reset() oraz toRequestParams(). Unikaj „magii”, która czyta ze stanu globalnego, chyba że to już ustalona reguła w aplikacji.

Po pilocie opublikuj krótką wewnętrzną wytyczną z jednym przykładem, który współpracownicy mogą skopiować. Jedna konkretna reguła bije długi dokument, np.: „Cała logika filtrowania tabeli żyje w composable; komponenty tylko wiążą kontrolki UI i wywołują apply().”

Zanim rozwiniesz podejście szerzej, użyj prostego kryterium ukończenia:

• Nowy kod czyta się tak samo w dwóch różnych komponentach.
• Testy pokrywają współdzieloną logikę bez montowania pełnego UI.
• Nowy współpracownik może zmienić regułę filtrowania bez dotykania niepowiązanych plików.

Jeśli twój zespół także buduje admin‑portale przy pomocy narzędzia no‑code jak AppMaster, zastosuj tę samą mentalność pilota: wybierz jeden workflow (np. zatwierdzenia), zdefiniuj zachowania, a potem ustandaryzuj wzorzec zanim rozciągniesz go po produkcie.

Popularne błędy i pułapki w dużych bibliotekach

Największe problemy w dużej bibliotece komponentów rzadko dotyczą składni. Pochodzą z małych lokalnych decyzji, które się kumulują i utrudniają reuse, testowanie i utrzymanie.

Jedną powszechną pułapką jest mieszanie wzorców losowo. Jeśli połowa biblioteki używa Options API, a druga połowa Composition API bez reguły, każdy nowy komponent staje się polem bitwy o styl. Kończysz z duplikującymi się rozwiązaniami tego samego problemu (formularze, tabele, uprawnienia), jedynie w różnych kształtach. Jeśli dopuszczasz oba style, napisz jasną politykę: nowy kod używa jednego stylu, legacy jest modyfikowane tylko gdy trzeba, a wspólna logika żyje w jednym uzgodnionym miejscu.

Inna pułapka to „bog‑composable”. Zwykle zaczyna się jako pomocne useAdminPage() lub useTable() i stopniowo pochłania routingu, fetchowania, cache, selekcji, dialogów, toastów i uprawnień. Trudno to testować, bo jedno wywołanie uruchamia wiele skutków ubocznych. Trudno też użyć tego ponownie, bo każdy ekran potrzebuje tylko 30% funkcji, ale płaci kosztem złożoności 100%.

Watchery to kolejne źródło bólu. Łatwo je dodać, gdy coś wydaje się niezsynchronizowane, ale później pojawiają się błędy timingowe (szczególnie z danymi asynchronicznymi i debounced inputami). Gdy użytkownicy zgłaszają „czasami traci mi zaznaczenie”, możesz spędzić godziny na odtwarzaniu problemu.

Czerwone flagi zwykle oznaczające kłopoty:

• Komponent działa tylko przy jednej, dokładnej kolejności propsów i eventów.
• Composable czyta i zapisuje stan globalny bez jasności.
• Kilka watcherów aktualizuje ten sam fragment stanu.
• Refaktory ciągle łamią ekrany konsumentów w małych miejscach.
• Współpracownicy unikają dotykania „tego pliku”, bo jest ryzykowny.

Ostatnia pułapka to łamanie publicznego API podczas refaktorów. W aplikacjach administracyjnych komponenty takie jak tabele, filtry i pola formularzy szybko się rozprzestrzeniają. Zmiana nazwy prop, emisji zdarzenia czy zachowania slotu może cicho złamać dziesiątki ekranów.

Bezpieczniejsze podejście to traktować API komponentów jak kontrakty: deprecjonuj zamiast usuwać, trzymaj shim kompatybilności przez jakiś czas i dodaj proste testy użycia, które montują komponent tak, jak robią to konsumenci. Jeśli generujesz interfejsy Vue 3 przy pomocy narzędzi takich jak AppMaster, to ma jeszcze większe znaczenie — spójne kontrakty komponentów ułatwiają ponowne użycie ekranów i przewidywalność zmian.

Szybkie kontrole przed podjęciem decyzji

Zanim wybierzesz Composition API, Options API lub mieszankę, zrób kilka szybkich kontroli na realnych komponentach z twojej biblioteki. Cel jest prosty: ułatwić znalezienie logiki, bezpieczne reuse i testowanie fragmentów, na których zależy administracja.

1) Czy ktoś może szybko znaleźć logikę?

Otwórz typowy, administracyjny komponent (filtry + tabela + uprawnienia + akcje zbiorcze). Udawaj, że jesteś nowy w kodzie.

Dobrą oznaką jest, gdy współpracownik potrafi odpowiedzieć „gdzie jest logika filtrowania?” albo „co decyduje, czy przycisk jest wyłączony?” w mniej niż 2 minuty. W Options API zwykle oznacza to, że logika jest jasno rozdzielona między computed, methods i watchery. W Composition API oznacza to, że setup() jest zorganizowane w małe, nazwane bloki (lub composable) i unika jednego wielkiego funkcjonalnego potwora.

2) Czy wspólne narzędzia zachowują się jak funkcje, a nie magia?

Niezależnie od wybranego wzorca, współdzielony kod powinien mieć jasne wejścia i wyjścia oraz minimalne skutki uboczne. Jeśli helper sięga do stanu globalnego, mutuje przekazane obiekty lub wywołuje sieciowo bez oczywistości, reuse staje się ryzykowny.

Szybka kontrola:

• Czy możesz przeczytać sygnaturę composable/helpera i zgadnąć, co zwraca?
• Czy możesz użyć go w dwóch komponentach bez ukrytego setupu?
• Czy możesz zresetować jego stan w testach bez sztuczek?

3) Czy testy skupiają się na zachowaniach administracyjnych?

Aplikacje administracyjne zawodzą w przewidywalny sposób: filtry działają źle, uprawnienia przepuszczają akcje, formularze walidują niekonsekwentnie, stan tabeli psuje się po edycji.

Zamiast testować wewnętrzne szczegóły implementacji (watchery vs refy), pisz testy wokół zachowań: „dla roli X akcja Y jest ukryta”, „zapisywanie pokazuje błąd i zachowuje dane wejściowe”, „zmiana filtru aktualizuje zapytanie i wiadomość o pustym stanie”. To utrzymuje testy stabilne nawet jeśli później przepniesz między stylami.

4) Czy macie standard dla stanu asynchronicznego?

Duże biblioteki mają wiele maleńkich przepływów asynchronicznych: ładowanie opcji, walidacja pól, pobieranie wierszy tabeli, retry przy błędzie. Jeśli każdy komponent wymyśla własne loading/error, onboarding i debugowanie się spowalniają.

Wybierz jeden jasny kształt stanu asynchronicznego (loading, error, retry, cancel). Composition API sprzyja reużywalnemu useAsyncX() composable, podczas gdy Options API może ustandaryzować data() i współdzielone metody. Najważniejsza jest spójność.

5) Czy publiczne API komponentów jest stabilne i samoopisujące?

Traktuj komponenty jak produkty. Ich propsy, emity i sloty to kontrakt. Jeśli ten kontrakt często się zmienia, każdy ekran administracyjny staje się kruchy.

Szukaj komentarzy wyjaśniających intencję (nie mechanikę): co propsy znaczą, jakie zdarzenia są gwarantowane i co jest uważane za wewnętrzne. Jeśli budujesz wewnętrzne narzędzia administracyjne z platformą taką jak AppMaster, to samo podejście pomaga: stabilne bloki budulcowe przyspieszają tworzenie kolejnych ekranów.

Przykładowy scenariusz i dalsze kroki dla twojego zespołu

Wyobraź sobie stronę administracyjną „Użytkownicy”, którą przebudowujesz: pasek filtrów (status, rola, data utworzenia), tabela z wybieralnymi wierszami, akcje zbiorcze (dezaktywuj, usuń, eksportuj) oraz uprawnienia oparte na rolach (tylko admini mogą usuwać zbiorczo, menedżerowie mogą edytować role).

W Composition API i Options API UI może wyglądać tak samo, ale kod zwykle organizuje się inaczej.

W Options API częściej masz jeden duży komponent z data dla filtrów i selekcji, computed dla stanów pochodnych i methods dla fetchowania, akcji zbiorczych i sprawdzeń uprawnień. Reuse pojawia się często jako mixiny lub współdzielone moduły helperów. To znajome, lecz powiązana logika może być rozproszona (fetch w methods, synchronizacja zapytań w watcherach, uprawnienia w computed).

W Composition API zwykle dzielisz stronę na skupione composable: jeden dla zapytań i filtrów, drugi dla selekcji wierszy i akcji zbiorczych, trzeci dla uprawnień. Komponent strony staje się zestawieniem tych kawałków, a logika dla każdego zagadnienia pozostaje razem. Kosztem jest potrzeba jasnego nazewnictwa i konwencji folderów, żeby współpracownicy nie czuli, że wszystko jest „magiczne w setup”.

Reuse pojawia się naturalnie w bibliotekach administracyjnych wokół filtrów synchronizowanych z URL, wzorców tabel po stronie serwera (paginacja, sortowanie, select‑all, straże akcji zbiorczych), sprawdzania uprawnień i spójnych stanów pustych/ładowania.

Plan kolejnych kroków, który działa w większości zespołów:

1. Wybierz domyślny styl dla nowego kodu i dopuszczaj wyjątki tylko z pisemnym uzasadnieniem.
2. Zdefiniuj konwencje: gdzie żyją composable, jak są nazywane, co mogą importować i co muszą zwracać.
3. Dodaj małą stronę referencyjną (np. tę stronę Użytkownicy) jako wzorzec dla struktury i wzorców.
4. Najpierw pisz testy dla części wielokrotnego użytku (filtry, uprawnienia, akcje zbiorcze), nie dla układu wizualnego.
5. Jeśli prędkość ważniejsza niż głęboka personalizacja dla niektórych ekranów, rozważ generowanie tych ekranów narzędziem no‑code jak AppMaster, a ręcznie pisana biblioteka niech skupia się na prawdziwie unikalnych częściach.

Jeśli już pracujesz z AppMaster, pomocne jest zachowanie tej samej filozofii między generowanymi a ręcznie pisanymi częściami: stabilne kontrakty komponentów i współdzielona logika opakowana w małe, jawne jednostki. Dla zespołów rozważających no‑code do narzędzi wewnętrznych, AppMaster (appmaster.io) jest zbudowany, by generować pełne aplikacje (backend, web, mobile) i jednocześnie pozwalać standaryzować warstwę web UI w Vue 3 tam, gdzie to się liczy.

Jeśli zrobisz w tym tygodniu tylko jedną rzecz, niech to będzie uczynienie strony Użytkownicy swoim wzorcem i egzekwowanie go w code review. Jeden jasny przykład zrobi więcej dla spójności niż długi style guide.