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.