BlockNSFW
Open-source browser extension for blocking adult websites and reducing unsafe content exposure across browsing, search, and selected social surfaces.
Project status:
- Published as Chrome and Firefox extension
- Already used by thousands of users
- Source-first repo with Chrome and Firefox build scripts
Current version: 2.0.2
Install
Badges
What It Does
BlockNSFW combines several protection layers:
- Network-level blocking: the curated list ships as a static
declarativeNetRequest ruleset, so a blocked host's images, media, frames and
scripts are refused by the browser before any request is sent. Navigation
still routes through the content script, which is what makes the blocked
page and its audit entry possible.
- Filtering inside embedded frames, not just the top page, with the work
scaled to the frame so ordinary pages stay fast.
- Domain blocking with local fallback rules plus cached remote blocklist updates. IDN / punycode hostnames (e.g.
xn--porn-tqa.net) are retained at runtime, not silently dropped.
- Hostname smart filter that scans both the ASCII / punycode form and the decoded Unicode form of a hostname, with multilingual adult-hostword coverage (Chinese, Korean, Russian, Arabic, Thai, plus transliterated Latin).
- Page and visible-content filtering through a Manifest V3 content script
- On-device AI image detection (opt-in). Two models: a bundled NSFW.js MobileNetV2, or Marqo's ViT-384 whose weights are fetched once on first use. Images are never uploaded.
- On-device AI text classification (opt-in, beta). Currently requires corroboration from the image scanner before it will block a page on its own.
- Search SafeSearch enforcement on Google, Bing, DuckDuckGo, Yahoo, Brave, Ecosia, Qwant, AOL Search, Presearch, and Yandex
- Optional DNS-based blocking through one of three filtering resolvers — Cloudflare for Families, AdGuard DNS Family, CleanBrowsing — or any DNS-over-HTTPS endpoint you supply
- Ruleset subscriptions: follow a blocklist someone else maintains, in uBlacklist's format. Subscribed lists can only ever add blocks, never remove them.
- PIN and access-code locks over the settings that would weaken protection
- Reddit NSFW subreddit checks for Reddit-specific filtering paths
- Optional Facebook Reels and Instagram Reels blocking toggles
- First-run onboarding, local stats, streak tracking, whitelist management, and audit views
- Back up and restore everything in one file (Settings › About › Your data); a backup never holds the PIN, the Pact or a Supporter code
- Manual community reports for blocked / missed sites
Architecture
Main files:
manifest.json - Chrome/Chromium MV3 manifestmanifest.firefox.json - Firefox MV3 manifestbackground.js - blocklist loading, DNS checks, dynamic rules, stats, audit storagecontent.js - page filtering, SafeSearch enforcement, Reddit checks, DOM scanningshared/hostname.js - browser-safe punycode / IDN helpers (RFC 3492)shared/host-keywords.js - shared smart-blocking keyword list and strict host matcherpopup.html / popup.js - quick toggle, stats, shortcutsoptions.html / options.js - full settings UI, whitelist tools, audit/stats accessblocked.html / blocked.js - blocked pageaudit.html / audit.js - audit viewstats.html / stats.js - statistics viewdata/HOSTS.txt - curated source blocklist (self-hosted in data/ under MIT)data/WHITELIST.txt - curated global whitelistdata/SOURCE_NOTES.txt - data-file provenance, curation policy, missed-site flowblocklist.json - bundled fallback blocklist (regenerated from data/HOSTS.txt)build-chrome.ps1 / build-firefox.ps1 - release bundle scripts
Tech stack:
- Manifest V3
- Vanilla JavaScript / HTML
- No Node build step required
Additional maintainer docs:
ARCHITECTURE.mdRELEASE_CHECKLIST.mdTHIRD_PARTY_NOTICES.md
Privacy and Network Behavior
Most filtering decisions happen locally in the browser, but this project is not fully offline.
Network requests may occur for these features:
- Remote blocklist and whitelist updates from GitHub-hosted text files
- A twice-daily update check against a small
version.json in this repository
- Optional DNS filtering through whichever resolver you select — Cloudflare for
Families, AdGuard DNS Family, CleanBrowsing, or a custom DNS-over-HTTPS
endpoint you provide. Queries go straight from your browser to
that resolver; nothing passes through our servers. A preset that stops
answering fails over to a second one on a different network; a custom
resolver deliberately does not
- Ruleset subscriptions, which fetch whichever URLs you have subscribed to,
once a day
- The optional ViT-384 image model's weights, fetched once from a GitHub-hosted
URL if you select that model. The traffic goes one way — your images are
never uploaded
- Reddit subreddit NSFW checks through Reddit endpoints
- Optional manual community reports through Appwrite-hosted backend
Privacy details live in PRIVACY_POLICY.md. Public docs should stay aligned with real code behavior.
Browser Support
Supported:
- Chrome 101+ (
requestDomains, used by the static ruleset, landed in 101)
- Firefox 113+
- Chromium-based browsers that support MV3 and required permissions
More detail: BROWSER_COMPATIBILITY.md
Local Development
Load unpacked in Chromium browsers
- Open
chrome://extensions/ or equivalent browser extensions page.
- Enable Developer Mode.
- Click Load unpacked.
- Select repo root containing
manifest.json.
Load temporary add-on in Firefox
- Open
about:debugging#/runtime/this-firefox.
- Click Load Temporary Add-on...
- Select
dist\firefox\manifest.json after running Firefox build script.
Build Release Bundles
Chrome:
powershell -ExecutionPolicy Bypass -File .\build-chrome.ps1
powershell -ExecutionPolicy Bypass -File .\build-chrome.ps1 -Zip
Firefox:
powershell -ExecutionPolicy Bypass -File .\build-firefox.ps1
powershell -ExecutionPolicy Bypass -File .\build-firefox.ps1 -Zip
A build from this repository alone is the open-source build: every
protection, without the Supporter extras (see "Open source, and the Supporter
extras" below). -Zip makes a store package and needs the extras; add
-OpenSource to package without them. A store package also refuses to
build while Supporter is still in Polar's sandbox (RELEASE_CHECKLIST.md,
section 0); -Zip -Sandbox makes a test package, never for a store.
Every zip is read back by scripts/check-package.js before the build calls
it done, and gets a build note (dist\blocknsfw-*.build.txt) with its
SHA-256 and the commits it was built from.
Build output:
dist\chrome\dist\firefox\
Manual Smoke Test
Before release:
- Load Chrome build and Firefox build.
- Confirm popup opens and main toggle works.
- Confirm options page opens and settings persist.
- Confirm blocked page, audit page, and stats page open correctly.
- Confirm SafeSearch rules apply on at least one supported engine.
- Confirm whitelist add/remove flow works.
- Confirm no obvious console errors after fresh install.
Firefox Rendering Benchmark
The repository includes a real-browser performance harness that launches clean
Firefox profiles under Xvfb, remotely drives them over WebDriver BiDi, and
compares a deterministic dynamic-feed workload with the extension absent and
installed:
npm run perf:firefox
See scripts/perf/README.md for shorter smoke runs,
workload controls, and JSON output.
Contributing
See .github/CONTRIBUTING.md.
If you want to report:
- blocking misses or false positives
- browser-specific regressions
- privacy/security concerns
- UX issues in popup/options flows
open an issue with steps, URLs/domains involved, browser version, and feature flags used.
Roadmap
Near-term priorities:
- tighten open-source launch polish
- add focused regression coverage for high-risk blocking logic
- improve release automation and browser-specific validation
License
MIT. See LICENSE.
Open source, and the Supporter extras
Everything that protects is open source and in this repository: the
blocklists, the AI image and text filters, SafeSearch and DNS, Gateways, the
Pact, Storm Mode and risk hours, your own words, all five blocked-page
designs, the first week of the path, statistics, and the Supporter page and
its code check. A build from here blocks exactly what the store version
blocks. (In the store versions Classic is the free design and the other four
come with Supporter; a build from here offers all five.)
The Supporter extras are not open source: days 8 to 30 of the path, the
evening check-in, Your good days, When it's hardest, Your month and Your
year, the photo and the voice message for the hard moment, your progress on
every computer (through the browser's own sync), and Supporter looks. They
live in a
private repository and ship only in the
versions on the Chrome Web Store, Microsoft Edge Add-ons and Firefox Add-ons.
extras/ holds empty stand-ins for them (extras/README.md), so a build
from here says plainly where an extra would be. The extras never decide what
is blocked and make no network requests.
Notes Before Public Launch
- Add store listing links once public repo announcement is ready
- Keep generated
dist/ output out of version control
- Keep docs consistent with actual network behavior and permissions
- Remote blocklist source is self-hosted in
data/ under MIT (see
THIRD_PARTY_NOTICES.md); background.js REMOTE_BLOCKLIST_URL and
REMOTE_WHITELIST_URL point at the public codepurse/BlockNSFW raw URLs
- Appwrite manual-report backend is maintained out-of-tree; its
public-launch status and the data it receives are documented in
THIRD_PARTY_NOTICES.md and PRIVACY_POLICY.md
