Soft-factory Browser Extension Template

Install (load unpacked)

Load the extension from source for local development. You will need a Chromium-based browser (Chrome, Edge, Brave, Arc).

Clone the template and run npm install at the root.
Run npm run build:ext to bundle the popup, options, background and content scripts via esbuild.
Open chrome://extensions/ in your browser.
Enable Developer mode in the top right.
Click Load unpacked and select the extension/ directory.
Pin the Soft-factory icon to the toolbar for quick access.

Build the extension

Three scripts are wired in package.json:

npm run build:ext     # esbuild bundles extension/ -> extension/
npm run build:landing # next build for the marketing site
npm run build         # both

The esbuild config lives at build/esbuild.config.mjs. It declares four entry points: the Preact popup, the Preact options page, the service worker, and the content script. JSX is automatic with Preact as the import source.

Manifest reference

The MV3 manifest at extension/manifest.json ships with the following surface:

action.default_popup = popup/popup.html
background.service_worker = background/service-worker.js (ESM)
options_page = options/options.html
content_scripts matches <all_urls> and injects content/content.js + content.css at document_idle.
permissions: storage, activeTab, scripting, contextMenus.
host_permissions: ["<all_urls>"]. Tighten this in production.
web_accessible_resources exposes the four icon sizes and the popup HTML for context menu actions.
default_locale = en, with _locales/zh/messages.json ready to use.

Content script API

The content script reads a CSS selector from chrome.storage.local and outlines matching elements with a 2px amber border. It exposes a tiny API on window.__softFactory:

window.__softFactory.count();    // number of highlighted elements
window.__softFactory.highlight(); // re-runs the highlight pass

The content script also sends factory/contentCount messages back to the background whenever the count changes. The popup can request a fresh count via factory/getCount.

Changing the target selector

Open the popup, switch to the Settings tab, edit the Target selector field. The content script observes chrome.storage.onChanged and re-runs immediately.

Troubleshooting

The popup does not open

Make sure the extension is enabled on chrome://extensions/ and that no error is shown in the service worker console.

Content script does nothing on some sites

The default selector is [data-soft-factory-target], a[href]. Some sites use shadow DOM or iframes. Switch the selector to one that matches the target, or wrap target elements with data-soft-factory-target.

build:ext fails with "cannot find module preact"

Run npm install at the template root. Preact is pinned at ^10.22.0.

service worker is idle and events get dropped

The service worker self-pings for 20 seconds after each meaningful event to keep itself alive. For long-running jobs use chrome.alarms instead.

Documentation