Як правильно впровадити content script у браузерне розширення?
Уявіть: ви розробили розширення для Chrome, яке підсвічує ціни на сторінці інтернет-магазину. Content script працює при першому завантаженні, але коли користувач переходить у кошик через pushState, скрипт перестає реагувати — MutationObserver не спрацьовує. Така ситуація — класика SPA-пасток. Ми стикаємося з подібними кейсами на кожному другому проєкті. У цій статті розберемо, як коректно впровадити content script, обробити SPA-навігацію, організувати обмін даними з background і уникнути типових помилок.
Content script — це механізм ін'єкції коду на сторінку. Ми інтегруємо content script — JavaScript-файл, який браузер впроваджує в контекст цільової сторінки в ізольованому середовищі, як зазначено в документації Chrome Extensions. Це дає доступ до DOM, але не до змінних сторінки, що є і захистом, і обмеженням. Наш досвід — 5+ років і 30+ успішних проєктів у сфері браузерних розширень. Content script призначений для модифікації DOM цільової сторінки.
Як браузер завантажує content script
У manifest.json (MV3) оголошуєте список скриптів та умови їх запуску. Параметр run_at визначає момент впровадження. Нижче — порівняння значень:
| run_at |
Момент впровадження |
Коли використовувати |
document_start |
До побудови DOM |
Для перехоплення початкових запитів |
document_end |
DOM готовий, ресурси ще завантажуються |
Для модифікації структури до рендерингу |
document_idle |
Після DOMContentLoaded |
Безпечний дефолт для більшості завдань |
{
"manifest_version": 3,
"content_scripts": [
{
"matches": ["https://*.example.com/*"],
"js": ["content/injected.js"],
"css": ["content/injected.css"],
"run_at": "document_idle",
"world": "ISOLATED"
}
]
}
Якщо потрібно впровадити скрипт динамічно — з service worker або на вимогу — використовуйте chrome.scripting.executeScript:
// background/service-worker.js
chrome.action.onClicked.addListener(async (tab) => {
await chrome.scripting.executeScript({
target: { tabId: tab.id, allFrames: false },
files: ['content/injected.js'],
world: 'ISOLATED'
});
});
Порівняння ISOLATED і MAIN world
| world |
Доступ до DOM |
Доступ до JS сторінки |
Ізоляція |
Коли використовувати |
| ISOLATED |
Повний |
Ні |
Висока |
За замовчуванням |
| MAIN |
Повний |
Повний |
Низька |
Monkey-patching, перехоплення викликів |
world: 'MAIN' дає доступ до змінних сторінки, але втрачає ізоляцію — використовуйте лише коли це дійсно потрібно (перехоплення викликів нативних API).
Чому content script не спрацьовує на SPA-сторінках?
При клієнтській навігації браузер не перезавантажує content script. MutationObserver на
— надійний спосіб відстежити зміну маршруту, і він ефективніший, ніж періодичний опитування через setInterval — різниця в продуктивності сягає 5 разів при частих переходах.
let lastUrl = location.href;
const urlObserver = new MutationObserver(() => {
if (location.href !== lastUrl) {
lastUrl = location.href;
onNavigate(location.href);
}
});
urlObserver.observe(document.querySelector('title') ?? document.head, {
subtree: true, characterData: true, childList: true
});
Робота з DOM
Content script бачить повний DOM, включаючи Shadow DOM. Для обробки динамічного контенту (SPA) обов'язковий MutationObserver. Приклад — підсвічування всіх цін на сторінці:
function highlightPrices() {
const walker = document.createTreeWalker(
document.body,
NodeFilter.SHOW_TEXT,
{
acceptNode(node) {
return /\$[\d,]+\.?\d{0,2}/.test(node.textContent)
? NodeFilter.FILTER_ACCEPT
: NodeFilter.FILTER_SKIP;
}
}
);
const nodes = [];
while (walker.nextNode()) nodes.push(walker.currentNode);
nodes.forEach(node => {
const span = document.createElement('span');
span.innerHTML = node.textContent.replace(
/(\$[\d,]+\.?\d{0,2})/g,
'<mark class="ext-price-highlight">$1</mark>'
);
node.parentNode.replaceChild(span, node);
});
}
const observer = new MutationObserver((mutations) => {
for (const mutation of mutations) {
if (mutation.addedNodes.length > 0) highlightPrices();
}
});
observer.observe(document.body, { childList: true, subtree: true });
highlightPrices();
У проєктах ми тестуємо до 10 цільових сайтів, обробляючи до 1000 DOM-вузлів за один прогін.
Спілкування з background service worker
Content script не має прямого доступу до chrome.tabs, тому використовуйте messaging. Для двостороннього потоку — встановлення порту:
// content/injected.js
const port = chrome.runtime.connect({ name: 'content-stream' });
port.onMessage.addListener((msg) => {
if (msg.type === 'DATA_CHUNK') appendChunk(msg.data);
});
port.postMessage({ type: 'START_STREAM', url: location.href });
Основний сценарій — одноразовий запит через chrome.runtime.sendMessage. Background має повернути true у колбеку, якщо відповідь асинхронна.
Як уникнути конфліктів стилів при впровадженні content script?
Два підходи: Shadow DOM для повної ізоляції інтерфейсу розширення або CSS з високою специфічністю та унікальними префіксами класів (наприклад, ext-). Якщо сторінка використовує строгу CSP, додавайте стилі через chrome.scripting.insertCSS з service worker.
Передача даних зі сторінки в content script
Оскільки JS-контексти ізольовані, використовуйте window.postMessage зі скрипта сторінки (або MAIN world) і ловіть повідомлення в content script з перевіркою event.source === window.
Що входить у роботу
Розробка content script під ключ включає:
- Налаштування маніфесту та декларацію скриптів.
- Обробку SPA-навігації та динамічного контенту.
- Інтеграцію з background service worker через messaging.
- Ізоляцію стилів та роботу з CSP.
- Тестування на цільових сторінках (до 10 сайтів).
- Документацію щодо використання та API розширення.
Типові проблеми та їх вирішення
Часта проблема — content script не спрацьовує після SPA-переходу. Рішення — MutationObserver на
. Інша проблема — CSP блокує inline-стилі — тоді використовуйте chrome.scripting.insertCSS. Для підвищення продуктивності важкі операції з DOM виконуйте в requestAnimationFrame, обходи — в requestIdleCallback.
Додаткові складнощі
- Якщо сторінка використовує Shadow DOM, переконайтеся, що ваш content script коректно проникає у відкриті shadow roots. Для закритих — без доступу.
- При роботі з iframe для впровадження у фрейми вкажіть
allFrames: true в налаштуваннях.
Ми гарантуємо стабільну роботу розширення в Chrome, Edge та Opera. Зв'яжіться з нами для оцінки вашого проєкту або замовте розробку content script під ключ. Отримайте консультацію безкоштовно — наші інженери допоможуть реалізувати content script будь-якої складності.
Фронтенд-розробка React: від аудиту до production
Бандл виріс до 3.1 MB gzip — це реальна цифра з проєкту, який прийшов до нас на аудит. Причина: moment.js (72 KB) тягнув локалі для всіх 160 мов, lodash імпортувався цілком замість tree-shake, три компонентні бібліотеки підключено одночасно. TTFB відмінний, але TTI (Time to Interactive) на мобільному — 14 секунд. Користувачі йшли, конверсія впала на 40%. Ми переписали фронтенд: прибрали дублювання бібліотек, впровадили динамічні імпорти та SSR. Результат — бандл зменшився до 850 KB gzip, TTI — 2.1 секунди, LCP — 1.8 с.
Frontend — це не «намалювати красиво». Це продуктивність, типізація, стратегія рендерингу, bundle management і підтримуваність на роки.
Чому Next.js — стандартний вибір для SEO?
React — наш основний UI-фреймворк для складних інтерфейсів. Next.js — стандартний вибір для проєктів з SEO-вимогами або SSR. App Router (з версії 13) приніс React Server Components, streaming та fetch із built-in кешуванням. Це реальні переваги: сторінка каталогу з тисячами товарів рендериться на сервері без відправки логіки фільтрації на клієнт, JS-бандл менший на 30%.
Але App Router — інший спосіб мислення. "use client" потрібно ставити свідомо. Реальна помилка: розробник позначає весь layout як "use client" через один стан навігації — і втрачає всі переваги RSC. Правило: тримати Server Components якомога вище в дереві, "use client" — тільки для інтерактивних листових компонентів. ISR (Incremental Static Regeneration) — потужний інструмент для контентних сайтів. На каталозі з 50 000 сторінок з ISR та CDN — TTFB < 50 ms для будь-якої сторінки.
Як TypeScript запобігає багам у продакшені?
TypeScript обов'язковий на будь-якому проєкті, який планується підтримувати довше 3 місяців або в команді більше одного розробника. Аргумент «пишемо швидко без типів» працює лише перші 2 тижні. Після — баги, пов'язані з невизначеними значеннями, виникають щотижня.
Конкретна користь: рефакторинг API-відповіді — змінив тип в одному місці, TypeScript показує всі місця, де потрібно адаптувати код. Без типів — баг у продакшені через тиждень. strict: true в tsconfig.json — обов'язково. noImplicitAny, strictNullChecks, strictFunctionTypes. Біль від Type 'undefined' is not assignable у розробці коштує менше, ніж Cannot read properties of undefined у продакшені. tRPC — end-to-end типізація від бекенду до фронтенду без окремої схеми — змінюючи тип процедури, ви одразу бачите місця на фронтенді, що потребують правки.
Vue 3 + Nuxt 3 — альтернативний стек для SSR
Vue 3 з Composition API — інший стиль розробки, ближчий до React Hooks. <script setup> та composables роблять код більш перевикористовуваним. Nuxt 3 — фреймворк для Vue з SSR/SSG, аналогічний Next.js. useAsyncData та useFetch — вбудовані composables з дедуплікацією запитів та hydration. Auto-imports зручні, але можуть заплутувати при debug. Nuxt Content — модуль для Markdown/MDX-файлів, ідеальний для документації.
Hydration mismatch — специфічний біль SSR на Vue та React. Рішення: <ClientOnly> компонент для браузерного контенту, suppressHydrationWarning для dynamic timestamps.
Продуктивність: метрики та інструменти
Bundle analysis — стартова точка. @next/bundle-analyzer або rollup-plugin-visualizer — запускаємо перед кожним мажорним деплоєм. Мета: жодна сторінка не повинна вимагати > 200 KB JS gzip для first paint.
Динамічні імпорти для важких компонентів:
const RichEditor = dynamic(() => import('@/components/RichEditor'), {
ssr: false,
loading: () => <EditorSkeleton />,
});
Редактор (Tiptap, Quill, CodeMirror) — типові кандидати на dynamic import. Без цього вони потрапляють в основний бандл. React DevTools Profiler — для пошуку зайвих ре-рендерів. React.memo, useMemo, useCallback — точкові інструменти. Передчасна мемоізація всього підряд додає overhead без користі. Профілюйте спочатку, оптимізуйте потім.
Віртуалізація довгих списків: @tanstack/virtual або react-window рендерять лише видимі елементи. Таблиця з 50 000 рядків: з віртуалізацією — 60fps, без — браузер зависає при скролі.
State management: без овериніжирингу
Для більшості додатків достатньо:
-
React Query / TanStack Query — для серверного стану (дані з API, кешування, інвалідація)
-
Zustand — для глобального клієнтського стану (легковаговий, без boilerplate Redux)
-
React Hook Form — для форм
Redux Toolkit виправданий для дуже складного глобального стану з великою кількістю взаємодій. Для більшості задач — це overkill. Recoil, Jotai — атомарні підходи для незалежних шматків стану.
CSS та дизайн-система
Tailwind CSS останньої версії — наш стандартний вибір для нових проєктів. Utility-first, відмінна інтеграція з компонентними бібліотеками (Radix UI, Headless UI), PostCSS pipeline. CSS Modules — альтернатива, коли потрібна більш явна ізоляція стилів. Radix UI + Tailwind (Shadcn/ui паттерн) — headless компоненти з повним контролем над стилями. Немає dependency lock-in: компоненти копіюються в проєкт і повністю кастомізуються. Storybook — для документування компонентної бібліотеки.
React DevTools Profiler — офіційний інструмент від команди React.
Тестування
| Рівень |
Інструмент |
Що тестуємо |
| Unit |
Vitest |
Утиліти, хуки, чисті функції |
| Component |
Testing Library |
Рендер, взаємодії |
| E2E |
Playwright |
Критичні користувацькі флоу |
| Visual |
Chromatic (Storybook) |
Регресія UI |
E2E тести через Playwright — для checkout, авторизації, критичних форм. Не для всього підряд: підтримка великої e2e-сюїти дорога, тому обираємо 3-5 ключових сценаріїв.
Орієнтири за термінами та складом робіт
| Задача |
Термін |
| SPA (дашборд, CRM-інтерфейс) |
8–16 тижнів |
| Next.js сайт з SSR/ISR |
6–14 тижнів |
| Frontend для існуючого API |
4–10 тижнів |
| Компонентна бібліотека |
6–12 тижнів |
Вартість розраховується після декомпозиції на компоненти, екрани та інтеграції з API. Ми використовуємо N+1 оцінку: додаємо 20% на ризики.
Що входить в роботу: вихідний код в Git, документація по архітектурі та компонентах, доступ до CI/CD, навчання вашої команди (2-3 зустрічі), гарантія 3 місяці на виявлені баги. Додатково — покриття юніт-тестами ключових модулів.
У нас 5 років досвіду у фронтенд-розробці, понад 50 виконаних проєктів, команда з 10 інженерів, що володіють React, Vue, Angular. Працюємо з технологіями, описаними в документації React та TypeScript. Додаткові відомості можна знайти в Wikipedia: React та Wikipedia: TypeScript.
Чек-лист типових помилок при початку проєкту
- Ігнорування tree-shaking: імпорт цілої бібліотеки замість вибіркових модулів.
- Відсутність code-splitting: важкий код завантажується одразу, а не на вимогу.
- Нехтування типобезпекою: відсутність
strict в tsconfig — прямий шлях до багів.
- Надмірна мемоізація:
useMemo та useCallback там, де вони не потрібні.
- Вибір невідповідного state-менеджера: Redux Toolkit на маленьких проєктах.
Який стек обрати для фронтенд-розробки React?
Ми порівнюємо інструменти за реальними метриками. Next.js швидший за Nuxt у збірці SSR на 20–30% при однаковому розмірі сторінки. TypeScript знижує кількість production-багів на 60–70% у порівнянні з JavaScript. Економія на підтримці такого проєкту — значна за рахунок скорочення часу на налагодження. Якщо вам потрібен легкий SPA з мінімальною вартістю — достатньо React + Vite. Для контентного сайту з SEO — Next.js з ISR дає TTFB нижче 50 мс навіть при 50 000 сторінок.
Отримайте консультацію по вашому проєкту: оцінимо поточний код і запропонуємо план оптимізації. Замовте аудит — знайдемо вузькі місця та покажемо, як скоротити бюджет без втрати якості.