@bloqr/compiler-core

Overview

@bloqr/compiler-core is this repository's own package — its canonical source lives at src/adblock-compiler-core/ and it's published to JSR. It replaced the AdGuard-maintained @adguard/hostlist-compiler npm package that the .NET, Python, and Rust compilers in this repo used to shell out to — they now shell out to @bloqr/compiler-core instead, and the TypeScript compiler is the package, compiling in-process.

It's a minimal, dependency-free compilation engine: no @adguard/agtree or other third-party AdGuard library, no Cloudflare-specific code, no commercial features. It's deliberately kept separate from Bloqr's commercial @bloqr/compiler product, which layers AST tooling, linting, plugins, and Cloudflare Workers deployment on top of AdGuard libraries.

Key Features

Quick Start

Installation

# Install from JSR
deno add jsr:@bloqr/compiler-core

# Or run directly without installation
deno run jsr:@bloqr/compiler-core/cli

Basic Usage

import { compile } from '@bloqr/compiler-core';

// Compile from configuration
const rules = await compile({
  name: "My Filter List",
  sources: [
    {
      source: "https://example.com/filters.txt"
    }
  ],
  transformations: ["Deduplicate", "RemoveEmptyLines"]
});

console.log(`Compiled ${rules.length} rules`);

CLI Usage

# Compile from config file
deno run --allow-read --allow-write --allow-env --allow-net --allow-run jsr:@bloqr/compiler-core/cli -c config.json

# Show version
deno run jsr:@bloqr/compiler-core/cli --version

How the Other Compilers Use It

The TypeScript compiler (src/adblock-compiler-core/) compiles in-process — it is this package. The .NET, Python, and Rust compilers shell out to it via Deno instead of maintaining their own copy of the engine:

deno run --allow-read --allow-write --allow-env --allow-net --allow-run \
  jsr:@bloqr/compiler-core/cli \
  --config config.json --output data/output/filters.txt

Each compiler keeps its own public API and field names unchanged across this migration — only what populates them changed. See the full guide for CI/CD integration examples (GitHub Actions, GitLab CI, Jenkins, Docker).

Configuration

@bloqr/compiler-core supports the same configuration schema as AdGuard's hostlist-compiler, so existing configurations carry over without changes.

Configuration Example (JSON)

{
  "name": "My Filter List",
  "description": "Custom ad-blocking filter",
  "version": "1.0.0",
  "sources": [
    {
      "name": "Local Rules",
      "source": "data/local.txt",
      "type": "adblock"
    },
    {
      "name": "EasyList",
      "source": "https://easylist.to/easylist/easylist.txt",
      "transformations": ["RemoveModifiers", "Validate"]
    }
  ],
  "transformations": ["Deduplicate", "RemoveEmptyLines", "InsertFinalNewLine"],
  "exclusions": ["*.google.com", "/analytics/"]
}

Available Transformations

1. ConvertToAscii - Convert internationalized domains
2. TrimLines - Remove whitespace
3. RemoveComments - Strip comments
4. Compress - Convert hosts to adblock syntax
5. RemoveModifiers - Remove unsupported modifiers
6. InvertAllow - Convert to allowlist
7. Validate - Remove invalid rules
8. ValidateAllowIp - Validate but keep IPs
9. Deduplicate - Remove duplicates
10. RemoveEmptyLines - Clean empty lines
11. InsertFinalNewLine - Add final newline

Documentation & Resources

Comparison with AdGuard's hostlist-compiler

@bloqr/compiler-core superseded @adguard/hostlist-compiler across every compiler in this repository — not as an npm-compatible fork with a fallback path, but as a full replacement.

Next Steps