Как правильно внедрить 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 — для глобального клиентского состояния (легковесный, без бойлерплейта 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. Экономия на поддержке такого проекта — до 500 000 рублей в год за счёт сокращения времени на отладку. Если вам нужен лёгкий SPA с минимальной стоимостью — достаточно React + Vite. Для контентного сайта с SEO — Next.js с ISR даёт TTFB ниже 50 мс даже при 50 000 страниц.
Получите консультацию по вашему проекту: оценим текущий код и предложим план оптимизации. Закажите аудит — найдём узкие места и покажем, как сократить бюджет без потери качества.