AdGuard Rules Editor

A browser-based library for editing and tokenizing AdGuard filter rules. It provides a CodeMirror 5 text editor with TextMate syntax highlighting (via WebAssembly Oniguruma), two tokenizers for custom rule rendering, and a RulesBuilder for programmatic rule construction.

Installation

pnpm add @adguard/rules-editor

Key Concepts

• Editor — a CodeMirror 5 instance with adblock syntax highlighting, powered by WASM-based Oniguruma regex via onigasm.
• Full tokenizer — splits a rule into highlighted segments using WASM; highest precision.
• Simple tokenizer — regex-based tokenizer without WASM; slightly less precise but no async setup required.
• RulesBuilder — factory class that constructs filter rules (block, unblock, no-filtering, DNS, comment, custom) via a builder pattern.
• Token — an enum of token types (keyword, operator, string, comment, etc.) shared by both tokenizers.

Quick Start

Editor

import { initEditor } from '@adguard/rules-editor';
import wasm from '@adguard/rules-editor/dist/onigasm.wasm';
import '@adguard/rules-editor/dist/codemirror.css';

const textarea = document.getElementById('textarea');
const editor = await initEditor(textarea, wasm, {
    hotkeys: { mode: 'mac' },
});
editor.setValue('||example.org^');

Tokenizing a Rule

import { getFullTokenizer, simpleTokenizer } from '@adguard/rules-editor';
import wasm from '@adguard/rules-editor/dist/onigasm.wasm';

// WASM-based (async init, higher precision)
const tokenize = await getFullTokenizer(wasm);
const tokens = tokenize('||example.org^$important');

// Simple (sync, no WASM)
const tokens2 = simpleTokenizer('||example.org^$important');

Building a Rule

import { RulesBuilder, BlockContentTypeModifiers, DomainModifiers } from '@adguard/rules-editor';

const rule = RulesBuilder.getRuleByType('block');
rule.setDomain('example.org');
rule.setContentType([BlockContentTypeModifiers.css, BlockContentTypeModifiers.scripts]);
rule.setHighPriority(true);
rule.setDomainModifiers(DomainModifiers.onlyListed, ['example.com', 'example.ru']);

rule.buildRule();
// => '||example.org^$stylesheet,script,domain=example.com|example.ru,important'

API

initEditor

async function initEditor(
    element: HTMLTextAreaElement,
    wasm: any,
    conf: {
        withBreakpoints?: boolean;
        onChange?: (editor: CodeMirror.Editor, makeMarker: () => HTMLDivElement) => void;
        hotkeys: {
            mode: 'windows' | 'mac';
            markerColor?: string;
            markerHTML?: string;
            toggleRule?: (editor: CodeMirror.Editor) => void;
            onSave?: (editor: CodeMirror.Editor) => void;
        };
        editor?: CodeMirror.EditorConfiguration;
        theme?: ITextmateThemePlus;
    },
): Promise<EditorFromTextArea>

| Parameter | Description | | --- | --- | | element | Textarea element to attach the editor to | | wasm | WASM binary (re-exported from onigasm) | | conf.hotkeys.mode | OS mode for hotkey mapping ('windows' or 'mac') | | conf.hotkeys.toggleRule | Callback for Ctrl/Cmd+/ (toggle rule) | | conf.hotkeys.onSave | Callback for Ctrl/Cmd+S | | conf.editor | Extra CodeMirror config | | conf.theme | Theme object for syntax highlighting | | conf.withBreakpoints | Enable breakpoint gutter | | conf.onChange | Editor change callback |

Returns a CodeMirror.EditorFromTextArea instance. See CodeMirror docs for events and commands.

getFullTokenizer

async function getFullTokenizer(
    wasm: any,
    theme?: ITextmateThemePlus,
): Promise<(rule: string) => RuleTokens>

Returns a tokenizer function. When theme is provided, the token field contains CSS class names from that theme instead of generic token names.

simpleTokenizer

function simpleTokenizer(rule: string): RuleTokens

Synchronous tokenizer. Same RuleTokens return type as the full tokenizer, but with slightly less granular splitting.

Tokenizer Comparison

For @@|https://example.org/file.js$domain=a.com|b.com:

| Tokenizer | Behavior | | --- | --- | | simpleTokenizer | Domain list as single string token | | getFullTokenizer | Domain list split per domain with operator separators |

RulesBuilder

class RulesBuilder {
    static getRuleByType(type: 'block'): BlockRequestRule;
    static getRuleByType(type: 'unblock'): UnblockRequestRule;
    static getRuleByType(type: 'noFiltering'): NoFilteringRule;
    static getRuleByType(type: 'custom'): CustomRule;
    static getRuleByType(type: 'comment'): Comment;

    static getDnsRuleByType(type: 'block'): DNSRule;
    static getDnsRuleByType(type: 'unblock'): DNSRule;
    static getDnsRuleByType(type: 'custom'): CustomRule;
    static getDnsRuleByType(type: 'comment'): Comment;

    static isDomainValid(domain: string): boolean;
    static isRuleValid(rule: string): boolean;
    static getRuleType(rule: string): RuleType | null;
    static getRuleFromRuleString(rule: string): BasicRule | null;
}

Rule types: 'block' | 'unblock' | 'noFiltering' | 'custom' | 'comment'

Common builder methods:

| Method | Description | | --- | --- | | setDomain(domain) | Set rule domain | | setContentType(modifiers[]) | Set content type modifiers | | setDomainModifiers(modifier, domains?) | Set domain scope | | setHighPriority(priority) | Add $important modifier | | buildRule() | Build the rule string |

DNS rule additionally has setIsIncludingSubdomains(bool).

Per-class differences:

• Comment — setText(text) / buildRule()
• CustomRule — setRule(rule) / buildRule() (returns rule as-is)
• NoFilteringRule — setDomain, getDomain, setContentType (accepts ExceptionSelectModifiers[]), setHighPriority, buildRule
• UnblockRequestRule — same as BlockRequestRule but accepts UnblockContentTypeModifier[]
• DNSRule — setDomain, getDomain, setIsIncludingSubdomains(bool), getIsIncludingSubdomains(), buildRule

Editor Helpers

// Extract rules with enabled/disabled state from editor
function getRulesFromEditor(
    editor: CodeMirror.Editor,
): { enabled: boolean; rule: string }[] | string;

// Set editor content with gutter markers for enabled rules
function setEditorValue(
    editor: CodeMirror.Editor,
    value: { enabled: boolean; rule: string }[],
    markerOptions: { color?: string; innerHTML?: string },
): void;

// Disable syntax highlighting when editor exceeds 1000 lines
function configureEditorMode(editor: CodeMirror.Editor): void;

WASM Re-export

The library re-exports the onigasm WASM binary for convenience:

import { wasm } from '@adguard/rules-editor';

Rendering Tokens (React Example)

import { simpleTokenizer } from '@adguard/rules-editor';

function HighlightedRule({ rule }: { rule: string }) {
    return (
        <>
            {simpleTokenizer(rule).map(({ token, str }, i) => (
                <span key={i} className={token ?? 'plain'}>
                    {str}
                </span>
            ))}
        </>
    );
}

Helper Exports

// Content type modifiers
export { BlockContentTypeModifiers, UnblockContentTypeModifier } from './rulesBuilder/rules/utils';
// Domain scope modifiers
export { DomainModifiers } from './rulesBuilder/rules/utils';
// Exception modifiers for noFiltering rules
export { ExceptionSelectModifiers } from './rulesBuilder/rules/utils';
// Rule type enums
export { RuleType, DnsRuleType } from './rulesBuilder/RulesBuilder';
// Token enum and RuleTokens type
export type { RuleTokens } from './lib/utils';

Documentation

• Development
• LLM agent rules
• Changelog