Spis treści
1. Dlaczego rozszerzenia przeglądarki są niedoceniane
Rozszerzenia przeglądarki zajmują unikalne miejsce: mają dostęp do stron, na których Twoi użytkownicy już pracują, nie wymagają osobnej instalacji aplikacji i mogą automatyzować workflow, który normalnie wymaga przełączania się między wieloma zakładkami.
Dla firm e-commerce to szczególnie potężne narzędzie. Rozszerzenie może wstrzyknąć porównanie cen bezpośrednio na stronę konkurencji, zautomatyzować operacje masowe w panelach marketplace'ów czy dodać fakturowanie jednym kliknięciem do panelu zarządzania zamówieniami.
ROI jest często natychmiastowy: zespoły raportują oszczędność 2-4 godzin dziennie na powtarzalnych zadaniach w przeglądarce po wdrożeniu dedykowanego rozszerzenia. To czas, który wraca bezpośrednio do rozwoju biznesu.
2. Stack: Vite + CRXJS + React + TypeScript
Nasz stack produkcyjny został dopracowany przez ponad 100 wersji rozszerzeń. Oto czego używamy i dlaczego:
Vite 8
Pracujemy na Vite 8 ze wsparciem wstecznym dla Vite 3, 4, 5, 6 i 7. Błyskawiczne buildy i natywne wsparcie ES modules. Development rozszerzeń wymaga ciągłego przeładowywania - Vite sprawia, że jest to niemal natychmiastowe. Koniec z czekaniem 30 sekund na rebuild webpacka. Bycie na najnowszej wersji oznacza, że zawsze masz najnowsze optymalizacje i łatki bezpieczeństwa.
CRXJS
Plugin Vite, który rozumie strukturę rozszerzeń Chrome. Stworzony przez Jacka i Amy, czyta Twój manifest.json i automatycznie obsługuje content scripts, background workers, popup pages i HMR. Jesteśmy kontrybutorami tego projektu (3.9k+ gwiazdek na GitHubie) i używamy go w każdym rozszerzeniu. Jako autorzy pluginów Vite rozumiemy API pluginów dogłębnie i potrafimy rozszerzać pipeline budowania, gdy to potrzebne.
React
Architektura komponentowa idealnie pasuje do rozszerzeń. Popup UI, strony opcji i wstrzykiwane UI content scriptów - to wszystko po prostu komponenty React. Nasza wewnętrzna biblioteka react-content-script-injector sprawia, że wstrzykiwanie komponentów React na dowolną stronę jest trywialne.
TypeScript
Typy Chrome API łapią błędy w czasie kompilacji, nie na produkcji. API rozszerzeń Chrome jest rozbudowane i ma wiele subtelnych ograniczeń typów - TypeScript ujawnia je zanim zrobią to Twoi użytkownicy.
TanStack Query
Cache'owanie danych i zarządzanie stanem serwerowym w standardzie branżowym. W rozszerzeniach efektywne cache'owanie jest kluczowe - potrzebujesz szybkiego dostępu do danych API bez bombardowania endpointów czy blokowania UI. TanStack Query obsługuje inwalidację cache, odświeżanie w tle i wzorce stale-while-revalidate out of the box, dzięki czemu UI rozszerzenia pozostaje responsywne, a dane aktualne.
Ten stack daje nam hot module replacement w content scriptach (tak, widzisz zmiany wstrzykiwane na żywą stronę bez odświeżania), typowo-bezpieczną komunikację między kontekstami rozszerzenia i doświadczenie developerskie jak przy budowaniu zwykłej aplikacji React.
Każde rozszerzenie, które budujemy, jest pokryte testami end-to-end, integracyjnymi i jednostkowymi. Testy E2E weryfikują pełną ścieżkę użytkownika w przeglądarce, testy integracyjne walidują poprawną komunikację między content scripts, background workers i popupami, a testy jednostkowe zabezpieczają poszczególne narzędzia i logikę biznesową. To warstwowe podejście łapie regresje zanim trafią na produkcję.
3. Manifest V3: co się naprawdę zmieniło
Manifest V3 (MV3) zastąpił V2 jako wymagany format rozszerzeń Chrome. Google wycofuje MV2, więc wszystkie nowe rozszerzenia muszą używać V3. Oto zmiany, które mają znaczenie w praktyce:
Background pages odchodzą. Service workers są event-driven i mogą być zabite przez przeglądarkę w dowolnym momencie. Nie można polegać na długo żyjącym stanie w tle - używaj chrome.storage lub chrome.alarms.
Stare API webRequest (do modyfikacji requestów) zastąpiono deklaratywnym systemem reguł. Jest bardziej restrykcyjne, ale wydajniejsze. Dla większości rozszerzeń biznesowych to nie jest bloker.
MV3 ma surowsze domyślne CSP. Koniec z eval() i inline scripts na stronach rozszerzenia. React i Vite radzą sobie z tym automatycznie, więc rzadko wpływa to na nasz workflow.
Praktyczny wpływ: jeśli budujesz od nowa, MV3 to po prostu sposób, w jaki rozszerzenia teraz działają - a my jesteśmy MV3 native. Każde rozszerzenie, które budujemy, startuje na Manifest V3 od pierwszego dnia, nie jako migracja z V2. Jeśli migrujesz starsze rozszerzenie z MV2, przejście na service workers jest największym wyzwaniem. Przeprowadziliśmy tę migrację dla wielu klientów i możemy pomóc.
4. Content scripts i wstrzykiwanie Reacta na strony
Content scripts to najpotężniejsza część rozszerzeń Chrome. Działają w kontekście stron internetowych, co oznacza, że mogą czytać i modyfikować DOM dowolnej strony (z odpowiednimi uprawnieniami).
Wyzwaniem jest wstrzyknięcie pełnego drzewa komponentów React na istniejącą stronę bez jej zepsucia. Dokładnie to rozwiązuje nasza wewnętrzna biblioteka react-content-script-injector:
Co robi react-content-script-injector
- -Monitoruje punkty wstrzyknięcia i automatycznie ponownie montuje komponenty, gdy aplikacja SPA hosta się przerenduje lub zmieni adres
- -Tworzy kontenery Shadow DOM z Tailwind CSS (lub dowolnymi stylami) wstrzykniętymi do shadow root
- -Raportuje błędy w czasie rzeczywistym od różnych użytkowników - feature flags i testy A/B na stronie hosta nigdy nie zepsują cicho rozszerzenia
- -Automatycznie obsługuje cleanup i ponowne wstrzyknięcie przy zmianach routingu po stronie klienta
- -Zapewnia narzędzia pozycjonowania (sidebar, floating panel, inline)
- -Obsługuje React Portals, dzięki czemu pełen React context (providery, stan, motyw) jest zawsze dostępny - nawet wewnątrz kontenerów Shadow DOM czy wstrzykiwanych paneli
Statyczne strony to łatwy przypadek - wstrzykujesz raz i gotowe. Trudna część to aplikacje React i SPA, gdzie DOM ciągle się zmienia, adresy zmieniają się bez przeładowania strony, a aplikacja hosta może testować A/B warianty, które przesuwają lub zmieniają elementy, do których celujesz. W tym się specjalizujemy i dlatego zbudowaliśmy tę bibliotekę.
5. Shadow DOM: izolacja stylów, która działa
Izolacja stylów to największy problem w developmencie content scriptów. Bez niej UI rozszerzenia dziedziczy style strony hosta - przyciski wyglądają źle, fonty się zmieniają, spacing się psuje. I odwrotnie - CSS rozszerzenia może przypadkowo zmienić wygląd strony hosta.
Shadow DOM zapewnia prawdziwą enkapsulację. Style wewnątrz shadow root nie wyciekają na zewnątrz, a style z zewnątrz nie wchodzą do środka. To krytyczne dla produkcyjnych rozszerzeń, które muszą działać na tysiącach różnych stron z różnymi resetami CSS, frameworkami i konfliktującymi nazwami klas.
Nasz react-content-script-injector obsługuje setup Shadow DOM automatycznie, włącznie z trudnymi częściami: wstrzykiwaniem Tailwinda do shadow root, ładowaniem fontów przez granicę shadow i prawidłowym działaniem portali (modale, dropdowny) w kontekście shadow. Ponieważ biblioteka natywnie zarządza React Portals, pełen React context - providery, stan, motyw - pozostaje dostępny wewnątrz każdego portalu, więc komponenty renderowane w Shadow DOM zachowują się dokładnie jak komponenty w normalnym drzewie React.
6. Komunikacja między kontekstami
Rozszerzenie Chrome ma wiele izolowanych kontekstów JavaScript: content script (działa na stronach), background service worker, popup i strony opcji. Komunikują się przez Chrome messaging API.
W praktyce wychodzi wzorzec podobny do architektury klient-serwer: service worker jest Twoim "serwerem" (obsługuje wywołania API, storage i logikę biznesową), a content scripts i popup to "klienci", którzy żądają danych i wyzwalają akcje.
Nasze najlepsze praktyki komunikacji
- 1.Definiuj typowane schematy wiadomości (discriminated unions w TypeScript dobrze się sprawdzają)
- 2.Logikę biznesową trzymaj w service workerze, logikę UI w content scriptach
- 3.Używaj
chrome.runtime.sendMessagedo wzorców request/response - 4.Używaj
chrome.runtime.connectdo długotrwałych połączeń (streaming danych) - 5.Zawsze obsługuj przypadek, gdy service worker nie jest jeszcze zainicjalizowany
Z TypeScriptem możesz sprawić, że komunikacja będzie w pełni typowo-bezpieczna: wiadomość typu "GET_PRICES" zawsze zwraca typowaną odpowiedź PriceData. To eliminuje całą klasę błędów runtime, które są trudne do debugowania między kontekstami.
7. Storage i zarządzanie stanem
Rozszerzenia mają własne API storage: chrome.storage.local dla danych lokalnych na urządzeniu i chrome.storage.sync dla danych, które podążają za użytkownikiem między urządzeniami. W przeciwieństwie do localStorage, są dostępne we wszystkich kontekstach rozszerzenia.
Dla złożonego stanu używamy lekkiego wzorca reaktywnego store: service worker trzyma źródło prawdy, a content scripts subskrybują zmiany przez chrome.storage.onChanged. Daje to synchronizację w czasie rzeczywistym między wszystkimi otwartymi kartami bez dodatkowej infrastruktury.
Ważne zastrzeżenie: chrome.storage.sync ma ścisłe limity rozmiaru (102 400 bajtów łącznie, 8 192 bajtów na element). Dla większych zbiorów danych używaj chrome.storage.local i obsłuż synchronizację między urządzeniami samodzielnie.
8. Wdrożenie i dystrybucja
Istnieją cztery główne kanały dystrybucji rozszerzeń Chrome:
Chrome Web Store (publiczny)
Standardowy kanał dystrybucji. Wymaga konta deweloperskiego Google (jednorazowa opłata $5), procesu weryfikacji (zwykle 1-3 dni robocze) i zgodności z politykami Chrome Web Store. Dobry dla narzędzi z szeroką publicznością.
Chrome Web Store (niewidoczny)
Ten sam sklep, ale rozszerzenie nie jest odkrywalne przez wyszukiwanie. Użytkownicy potrzebują bezpośredniego linku. Idealny dla narzędzi wewnętrznych i rozszerzeń dedykowanych klientom. Nadal przechodzi weryfikację.
Sideloading enterprise
Dla organizacji z Google Workspace lub zarządzanymi przeglądarkami Chrome. Rozszerzenia można wymusić instalację przez Group Policy bez przechodzenia przez sklep. Bez weryfikacji, natychmiastowe aktualizacje.
Automatyczna instalacja dla testerów z GitHub
Budujemy dedykowane programy instalacyjne, które automatycznie wgrywają nowe wersje rozszerzenia na komputery testerów QA. Każdy push uruchamia build CI/CD, a nasz instalator pobiera najnowszy artefakt z GitHub i aktualizuje rozszerzenie w przeglądarce testera automatycznie - bez ręcznego pobierania, bez przeciągania plików, bez weryfikacji w sklepie. QA zawsze pracuje na najnowszym buildzie bez kiwnięcia palcem, skracając pętlę feedbacku z dni do minut.
Obsługujemy cały pipeline wdrożenia: build, pakowanie, przesłanie i iterację na feedbacku z weryfikacji. Nasze CI/CD automatycznie podbija wersje rozszerzenia i paczek, buduje artefakt i wdraża bezpośrednio na Chrome Web Store - dzięki czemu każdy merge do main to potencjalny release. Dla testerów ten sam pipeline publikuje instalowalne buildy na GitHub. Dla klientów enterprise dodajemy dystrybucję przez Group Policy.
9. Najczęstsze błędy, które widzieliśmy
Po zbudowaniu i przeglądzie dziesiątek rozszerzeń, to są wzorce, które powodują najwięcej problemów:
Przechowywanie stanu w background page
W MV3 service workers kontekst tła może być zabity w dowolnym momencie. Cały stan w pamięci jest tracony. Zawsze zapisuj ważny stan do chrome.storage.
Brak obsługi nawigacji SPA
Wiele nowoczesnych aplikacji używa routingu po stronie klienta. Content script jest wstrzykiwany raz przy załadowaniu strony, ale URL może się zmienić bez pełnego przeładowania. Użyj MutationObserver lub API webNavigation do wykrywania tych przejść.
Żądanie zbyt wielu uprawnień
Użytkownicy widzą listę uprawnień przed instalacją. Żądanie "dostępu do wszystkich stron", gdy potrzebujesz dostępu tylko do jednej domeny, obniży Twój wskaźnik instalacji. Używaj minimalnych wymaganych uprawnień i rozważ opcjonalne uprawnienia dla zaawansowanych funkcji.
Ignorowanie procesu weryfikacji Chrome Web Store
Google weryfikuje każdą aktualizację rozszerzenia. Jeśli używasz zdalnego wykonywania kodu, nadmiernych uprawnień lub wzorców wyglądających na zbieranie danych, Twoja aktualizacja zostanie odrzucona. Poznaj zasady zanim zaczniesz budować.
Brak izolacji stylów w content scripts
Bez Shadow DOM lub równoważnej izolacji, Twoje rozszerzenie będzie wyglądać inaczej na każdej stronie. Widzieliśmy rozszerzenia, które działają idealnie na jednej stronie, a na innej są kompletnie zepsute z powodu konfliktów CSS.
Potrzebujesz pomocy z rozszerzeniem?
Jesteśmy kontrybutorami CRXJS z ponad 100 wydanymi wersjami rozszerzeń produkcyjnych. Niezależnie czy potrzebujesz nowego rozszerzenia od zera, czy pomocy z migracją do Manifest V3, możemy pomóc.