
Product
Announcing Precomputed Reachability Analysis in Socket
Socket’s precomputed reachability slashes false positives by flagging up to 80% of vulnerabilities as irrelevant, with no setup and instant results.
@eyeo/snippets
Advanced tools
This module goal is to provide a pre-bundled, pre-tested, and pre-optimized version of all snippets used in various mobile, or desktop, Ads blockers.
Each snippet is represented as a filter text, defined through #$#
syntax, followed by the snippet name and zero, one, or more arguments separated by a space or, when spaces are part of the argument, included in quotes.
! logs 1 2 3 in the console
evilsite.com#$#log 1 2 3
Multiple snippets can be executed per single filter by using a semicolon ;
in between calls.
! logs 1 2 then 3 4 5 in the console
evilsite.com#$#log 1 2; log 3 4 5
Snippets can run either as content script, which is a separate environment that replicates the DOM but never interferes with the JS that is running on the user page (and vice-versa), or as injected script that runs on the page among 3rd party and regular site's JS code.
The former kind is called isolated, because it runs sandboxed through the Web extension API, while the latter kind is called main, or injected, because it requires evaluation within the rest of the code that runs in the page, hence it's literally injected into such page.
Some snippet might be just an utility and, as such, be available in both the main and the isolated worlds. The way this snippet gets executed, and its possible side effects, remain confined within the isolated or main "world" it runs into.
This module currently provides the following exports:
@eyeo/snippets
which includes both isolated
and main
, aliased also as injected
, export names@eyeo/snippets/isolated
which includes only the isolated
export@eyeo/snippets/main
, aliased as @eyeo/snippets/injected
too, which includes only the main
export@eyeo/all
which exports all snippets, as single callback for those environments where the isolated world is not supported, but standard ESM is usedAccordingly to the project needs, this module can be used in various ways.
Please always check our releases page and feel free to use URLs that point at our released branches, via https://gitlab.com/eyeo/snippets/-/raw/RELEASE_VERSION/dist/YOUR_FILE_HERE.js
, where RELEASE_VERSION
can be v0.5.0
or others, and YOUR_FILE_HERE
is:
Both main.js
and isolated.js
are also there for possible testing purpose, containing the same code other files have.
Their source code is the exact same available in the webext folder and its source files.
With the release of snippets module version 0.8.0, we introduced a new snippet called hide-if-matches-xpath3
that allows using XPath 3.1 functions to target ads. As XPath 3.1 is not supported natively by the browsers, the snippet requires injecting a dependency into the isolated context to work properly. This dependency is automatically injected using existing mechanisms for web extensions, if you are using eyeo's Web Extension Ad Blocking Toolkit. For Chromium based products, the dependency injection logic will be supported by eyeo Browser Ad-Filtering Solution .
As a Chromium-based product, if you are using the @eyeo/snippets
module as a standalone library you would need to actively opt-in to be able to use the hide-if-matches-xpath3
snippet. You can keep using the isolated-first.jst
artifact without any changes to your existing build steps. isolated-first.jst
does not include hide-if-matches-xpath3
snippet but it will keep being supported. If you want to include the hide-if-matches-xpath3
snippet you would need to do two steps. First you would need to use isolated-first-all.jst artifact instead. Secondly you would need to implement the dependency injection logic so that the required dependencies are included before the snippet runs. You can do this by injecting the dependencies.jst artifact into the page and calling the dependency function: hideIfMatchesXPath3Dependency()
. The snippet should work as expected after that.
The source folder contains all the files used to create artifacts in both dist folder and webext folder.
The former contains files used by 3rd party, non Web Extension related, projects, while the webext folder contains both optimized and source version of the files, so that it is possible to eventually offer a debugging mode instead of a production one.
This module is used by both Web Extensions and 3rd party partners and, even if the source code is always the same, these are different targets.
This section would like to explain, on a high level, the difference among these folders.
This folder contains all exports defined as ECMAScript standard module (aka ESM) within the package.json
file.
Both main and isolated exports are pure functions that can get passed to the Manifest v3 scripting API.
These functions have been augmented like a read-only Map via a .has(snippetName)
and .get(snipetName)
where:
.has(...)
returns true if the snippets is known for that specific world (either MAIN or ISOLATED).get(...)
returns either null or a callback that is used as dependency for that very specific scriptThis approach gives us the ability to execute the minimum amount of code whenever such snippet is not needed for that specific page, as dependencies can indeed be quite big (in this case a stripped version of the TensorFlow Library + a binary model).
These callbacks are usually not used, nor needed, by other 3rd party snippets' consumers.
This folder contains files that can be embedded directly as part of any HTML page and executed right away through surrounding text:
// example of distFileContent source code
// distFileContent = readFileSync("dist/snippets.js")
// distFileContent = readFileSync("dist/isolated-first.jst")
page.evaluate(`(${distFileContent})(...${JSON.stringify([env, ...snippets])})`);
In the snippets.js
case we have all snippets except the ML one embedded into a single callback, and all snippets run in the MAIN world.
The isolated-first.jst
file instead executes right away any ISOLATED snippet and, if there's anything in the MAIN world to execute too, it contains itself some logic to append a script on the user page that runs MAIN world snippets right after, still passing along the very same arguments it received through [env, ...snippets]
serialization.
The .jst
extension means JS Template and it's been chosen because otherwise some toolchain might try to automatically minify such file and, because its content is not referenced anyway as that's just a callback that's not even executed right away, the minifier could decide to entirely drop its content.
We came up with a template extension to avoid minifiers embedded in toolchains (i.e. Android) to actually break our code once injected.
Other files in the dist folder offer, like it is for the webext one, full source code alternatives or any other possible alternative as just isolated.js or main.js could be.
Plase note these files in the dist folder are not exported as module but are used through release tags as explained in the previous session.
We try to follow official guidance from GitLab through the following steps:
git checkout -b vX.X.X
npm run build.assets ~/gitlab/abp-snippets/source
to import source code files into this repositorybundle/main.js
(if it needs to be injected to main context) or bundle/isolated.js
(if it needs to be injected into the isolated context)npm run build
to create all artifacts after a cleanupvX.X.X
, using @eyeo/snippets vX.X.X as commit messagedist
, webext
, and the source
folder while reviewing changes, as these will always be differnt in a way or anothergit push --set-upstream origin vX.X.X
and then create a descriptive release MR following this template:## Background / User story
A brief description of why we are releasing.
## Dependency changes
* **Name**: @eyeo/snippets
* **Version**: vX.X.X
* **Breaking changes**: none, or a meaningful and detailed description about any breaking change
* **Other changes**:
* a description
* of all the *patches* landing
* within this release
## New features
A description of any new snippet or feature that is not a patch and it improves the library or filtes ability.
In case of multiple new features, consider splitting these via `### Heading 3` for easy exact links references.
## Deprecations
A list of all deprecations landing with this version.
## Integration notes
A description of any particular change or extra work any module consumer should be aware of.
npm version [mayor|minor|patch] -m "@eyeo/snippets v%s"
git push vX.X.X
git push --tags
vX.X.X
main
branchmain
, pull and run npm publish
being sure you have access rights and a 2FA protected accountFAQs
eye/o snippets for Ads blocker
The npm package @eyeo/snippets receives a total of 13,700 weekly downloads. As such, @eyeo/snippets popularity was classified as popular.
We found that @eyeo/snippets demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket’s precomputed reachability slashes false positives by flagging up to 80% of vulnerabilities as irrelevant, with no setup and instant results.
Product
Socket is launching experimental protection for Chrome extensions, scanning for malware and risky permissions to prevent silent supply chain attacks.
Product
Add secure dependency scanning to Claude Desktop with Socket MCP, a one-click extension that keeps your coding conversations safe from malicious packages.