Как превратить Greasemonkey-скрипт в расширение Firefox

Анимация процесса конвертации Greasemonkey-скрипта в расширение

Важно: перед распространением получите разрешение автора скрипта и укажите лицензию. Если автор уже разрешил перераспространение, добавьте атрибуцию.

Введение

Greasemonkey — удобный способ изменять поведение веб‑страниц с помощью пользовательских JavaScript. Но для непрофессионального пользователя установка Greasemonkey и затем дополнительных скриптов может оказаться сложной. Конвертация .js в .xpi (расширение Firefox) упрощает установку: пользователь просто устанавливает расширение, как любое другое.

На практике есть два подхода:

Быстро: использовать онлайн‑инструмент (в исходном примере — “User Script Compiler”).
Контролируемо: создать вручную WebExtension (manifest.json) и упаковать в .xpi.

Иллюстрация: иконка расширения Firefox и упаковка в XPI

Кому это полезно

Авторам скриптов, которые хотят шире распространять свои решения.
Разработчикам, готовящим наборы улучшений для команды или клиентов.
Пользователям, которых сложно научить устанавливать скрипты вручную.

Что нужно иметь перед началом

Исходный Greasemonkey‑скрипт в .js.
Доступ к компьютеру с Firefox и правам на установку расширений.
(Опционально) текстовый редактор и умение переименовать файл.

Пошаговая методика (быстрый путь через онлайн‑компилятор)

Найдите .js‑файл скрипта в папке профиля Firefox: подпапка gm_scripts. Или скачайте с репозитория (Userscripts.org и аналоги).
Правый клик → Переименовать (Rename) и измените расширение .js → .txt, затем откройте файл в блокноте и скопируйте весь код.
Откройте “User Script Compiler” (или аналог) и вставьте код в поле User Script. Заполните данные автора, версию и описание.
Нажмите «compile». Инструмент сгенерирует .xpi и предложит сохранить файл.
Для установки перетащите .xpi в окно Firefox или откройте его в браузере. Подтвердите установку и перезапустите браузер при необходимости.
Удалите оригинальный Greasemonkey‑скрипт, если он больше не нужен. Отправьте копию .xpi автору скрипта, если хотите быть вежливы.

Классический способ установки: перетяните .xpi из Проводника в окно Firefox и подтвердите.

Пошаговая методика (контролируемая, через WebExtension)

Создайте папку проекта: my-extension/.
В корне создайте файл manifest.json (пример ниже).
Поместите ваш скрипт в папку, например scripts/userscript.js.
Если скрипт использует специальные Greasemonkey API (GM_*), адаптируйте их: замените вызовы на стандартные WebExtension API или включите shim.
Соберите .xpi: упакуйте содержимое в ZIP и переименуйте в .xpi, либо используйте инструмент web-ext (рекомендуется для отладки).

Пример минимального manifest.json для встраивания пользовательского скрипта как фонового контента или content script:

{
  "manifest_version": 2,
  "name": "Моё расширение из userscript",
  "version": "1.0.0",
  "description": "Версия userscript, упакованная как расширение",
  "content_scripts": [
    {
      "matches": ["*://*/*"],
      "js": ["scripts/userscript.js"],
      "run_at": "document_end"
    }
  ],
  "icons": {
    "48": "icons/icon-48.png"
  }
}

Примечание: manifest_version 2 — пример совместимости с классическими WebExtension. Уточните требования к версии манифеста для целевой версии Firefox.

Когда это не сработает или может дать сбои

Скрипт использует специализированные GM_ API (GM_getValue, GM_setValue, GM_xmlhttpRequest) без полифила — такие вызовы нужно адаптировать.
Скрипт ожидает специфического окружения Greasemonkey (строки метаданных @grant, @include). Потребуется корректировать метаданные в коде.
Если скрипт полагается на устаревшие приватные API браузера — возможны ошибки.
Некоторые скрипты работают только в контексте пользователей (например, доступ к настройкам Greasemonkey) и не будут корректно работать в виде расширения без доработки.

Важно тестировать поведение на тех сайтах, для которых предназначен скрипт.

Альтернативные подходы

Пакетировать пользователейский скрипт как отдельный пользовательский модуль, требующий Greasemonkey/Tampermonkey — проще, но сложнее для конечного пользователя.
Переписать скрипт как полноценный WebExtension с опциями и интерфейсом для управления настройками.
Использовать менеджеры пользователейcript (Tampermonkey) с экспортом настроек и ссылкой на установочный .user.js.

Чек‑лист перед публикацией (для автора)

Получено разрешение на распространение (если код не ваш).
Указана лицензия и атрибуция автора.
Скрипт протестирован в чистом профиле Firefox.
Все вызовы GM_* адаптированы или заменены.
Указаны поддерживаемые URL в matches или в коде.
Версия и описание в manifest.json корректны.
Иконки и файлы локализации включены.

Роль‑ориентированные проверки

Разработчик:

Проверяет совместимость API и безопасность сетевых запросов.
Обеспечивает обработку ошибок и логирование.

Тестировщик:

Тестирует на страницах, указанных в matches.
Проверяет обновление/удаление расширения.

Конечный пользователь:

Легко устанавливает .xpi и видит ожидаемое поведение.
Не требуется ручная установка дополнительных расширений.

Критерии приёмки

Расширение устанавливается через .xpi без ошибок.
Сценарии, для которых предназначен скрипт, работают корректно на поддерживаемых сайтах.
Нет утечек данных и нежелательных сетевых запросов (проверено).
При удалении расширения сайт возвращается к исходному состоянию.

Тест‑кейсы / критерии приёмки (коротко)

Установка: перетягивание .xpi → подтверждение установки → расширение отображается в about:addons.
Функциональность: все ключевые функции скрипта выполняются на целевых URL.
Отказоустойчивость: при ошибке в скрипте страница не ломается полностью; ошибки логируются в консоль.
Совместимость: не конфликтует с другими популярными расширениями.

Шаблон сообщения автору скрипта

Здравствуйте,

я упаковал ваш userscript в расширение Firefox (.xpi), чтобы упростить установку для менее технически подкованных пользователей. Хочу убедиться, что вы не против распространения. Готов отправить вам .xpi и поместить ссылку с вашей атрибуцией.

С уважением, [Ваше имя]

Советы по безопасности и конфиденциальности

Не включайте в расширение секреты, API‑ключи или персональные токены.
Явно опишите, какие сетевые запросы выполняет расширение.
Если расширение запрашивает дополнительные разрешения, объясните почему.

Совместимость и миграция

WebExtension‑модель — путь к стабильной поддержке современных версий Firefox.
Проверяйте, какие разрешения требуются в manifest.json. Чем уже набор разрешений — тем выше вероятность прохождения у пользователя.
Для сложных GM_* API используйте адаптационный слой (shim) или перепишите функционал через WebExtension API.

Примеры отказов и обходы

Если userscript активно использует GM_xmlhttpRequest: заменить на background fetch с использованием fetch() и message passing.
Если скрипт хранит большие объёмы данных через GM_setValue: использовать storage.local WebExtension.

Резюме

Пакетирование Greasemonkey‑скрипта в .xpi делает установку проще и повышает доступность для обычных пользователей. Быстрый путь — онлайн‑компилятор; контролируемый путь — создание WebExtension с manifest.json. Важно адаптировать API, соблюдать лицензию и протестировать расширение перед распространением.

Замечание: существуют другие инструменты и подходы; выбирайте тот, который даёт баланс между скоростью и контролем над кодом.

Капсула: если хотите, могу подготовить минимальный manifest.json под конкретный скрипт или помочь адаптировать вызовы GM_*.

Скриншот: пример полей компилятора и итоговый XPI

Иллюстрация: пример заполнения полей в онлайн‑компиляторе и сохранённый .xpi файл.

Короткое объявление (100–200 слов)

Преобразование Greasemonkey‑скриптов в расширения Firefox (.xpi) упрощает установку и распространение среди пользователей. Вы можете быстро скомпилировать .js в .xpi с помощью онлайн‑компилятора или создать контролируемую WebExtension с manifest.json. Перед публикацией проверьте совместимость вызовов GM_*, укажите лицензию и протестируйте расширение на целевых сайтах. Это удобный путь сделать полезные улучшения веб‑страниц доступными широкому кругу пользователей без необходимости объяснять последовательность установки Greasemonkey и скриптов.