FAQ
The things that come up most often when running the extension unpacked.
Problems
A site broke after I raised the blocking level
Click the toolbar icon on that page and choose safe mode — every feature pauses for that
site only. If you would rather keep ad blocking, add the site to the whitelist with the
aggressive features switched off instead. smart-recovery.js also watches for
pages that fail to load and offers the same fix inline.
The popup says some blocking rules did not load
Chrome caps how many declarative rules an extension may enable at once, and another ad blocker can fill that budget. The extension detects the shortfall, retries, and shows a repair banner — try reloading the rules from that banner, or disable the other blocker.
Settings reset after I moved the folder
An unpacked extension's ID is derived from its folder path. Moving or renaming the folder gives it a new identity, so storage starts empty. Keep the folder where it is, or install from a release zip in a stable location.
Chrome keeps creating a _metadata/ folder
That is a Chrome artifact written when an unpacked extension loads. It is in
.gitignore — leave it uncommitted.
Dark mode does not match my system
The popup follows the System / Light / Dark setting in its own settings and applies it
through color-scheme. If you changed your OS theme while the popup was open,
reopen the popup.
Development
How do I cut a release?
Run npm run bump minor (or patch/major), fill in the changelog, commit, then
tag v<version> and push with --follow-tags. The release
workflow builds and attaches the zip. The full flow is on the
Versioning page.
Where do the user-facing strings live?
_locales/<lang>/messages.json. manifest.json references them
through __MSG_appName__ and __MSG_appDesc__, and the popup reads the
same catalogue through i18n.js.
How do I change the popup colours?
Edit the design tokens in assets/popup-*.css. Every colour is a custom property
defined once with light-dark(light, dark), so one edit covers both themes. No
markup or JavaScript needs to change.
Why is the repository 46 MB?
Roughly 34 MB of it is the blocklists under rules/. They ship with the
extension and are not fetched at runtime.
Can I build the store zip without tagging?
Yes — npm run package writes dist/freerammer-v<version>.zip
from whatever is in the working tree.