Migration Guide

Migrating from @adguard/hostlist-compiler to AdBlock Compiler.

Overview

AdBlock Compiler is a drop-in replacement for @adguard/hostlist-compiler with the same API surface and enhanced features. The migration process is straightforward and requires minimal code changes.

Why Migrate?

✅ Same API - No breaking changes to core functionality
✅ Better Performance - Gzip compression, request deduplication, smart caching
✅ Production Ready - Circuit breaker, rate limiting, error handling
✅ Modern Stack - Deno-native, zero Node.js dependencies
✅ Cloudflare Workers - Deploy as serverless functions
✅ Real-time Progress - Server-Sent Events for compilation tracking
✅ Visual Diff - See changes between compilations
✅ Batch Processing - Compile multiple lists in parallel

Quick Migration

1. Update Package Reference

npm/Node.js:

{
    "dependencies": {
        "@adguard/hostlist-compiler": "^1.0.39", // OLD
        "@jk-com/adblock-compiler": "^0.6.0" // NEW
    }
}

Deno:

// OLD
import { compile } from 'npm:@adguard/hostlist-compiler@^1.0.39';

// NEW
import { compile } from 'jsr:@jk-com/adblock-compiler@^0.6.0';

2. Update Imports

Replace all import statements:

// OLD
import { compile, FilterCompiler } from '@adguard/hostlist-compiler';

// NEW
import { compile, FilterCompiler } from '@jk-com/adblock-compiler';

That's it! Your code should work without any other changes.

API Compatibility

Core Functions

All core functions remain unchanged:

// compile() - SAME API
const rules = await compile(configuration);

// FilterCompiler class - SAME API
const compiler = new FilterCompiler();
const result = await compiler.compile(configuration);

Configuration Schema

The configuration schema is 100% compatible:

interface IConfiguration {
    name: string;
    description?: string;
    homepage?: string;
    license?: string;
    version?: string;
    sources: ISource[];
    transformations?: TransformationType[];
    exclusions?: string[];
    exclusions_sources?: string[];
    inclusions?: string[];
    inclusions_sources?: string[];
}

Transformations

All 11 transformations are supported with identical behavior:

ConvertToAscii
TrimLines
RemoveComments
Compress
RemoveModifiers
InvertAllow
Validate
ValidateAllowIp
Deduplicate
RemoveEmptyLines
InsertFinalNewLine

New Features (Optional)

After migrating, you can optionally use new features:

Server-Sent Events

import { WorkerCompiler } from '@jk-com/adblock-compiler';

const compiler = new WorkerCompiler({
    events: {
        onSourceStart: (event) => console.log('Fetching:', event.source.name),
        onProgress: (event) => console.log(`${event.current}/${event.total}`),
        onCompilationComplete: (event) => console.log('Done!', event.ruleCount),
    },
});

await compiler.compileWithMetrics(configuration, true);

Batch Compilation API

// Using the deployed API
const response = await fetch('https://adblock-compiler.jayson-knight.workers.dev/compile/batch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        requests: [
            { id: 'list-1', configuration: config1 },
            { id: 'list-2', configuration: config2 },
        ],
    }),
});

const { results } = await response.json();

Visual Diff

Use the Web UI at https://adblock-compiler.jayson-knight.workers.dev/ to see visual diffs between compilations.

Platform-Specific Migration

Node.js Projects

Before:

const { compile } = require('@adguard/hostlist-compiler');

After:

// Install via npm
npm install @jk-com/adblock-compiler

// Use the package
const { compile } = require('@jk-com/adblock-compiler');

Deno Projects

Before:

import { compile } from 'npm:@adguard/hostlist-compiler';

After:

// Preferred: Use JSR
import { compile } from 'jsr:@jk-com/adblock-compiler';

// Or via npm compatibility
import { compile } from 'npm:@jk-com/adblock-compiler';

TypeScript Projects

Before:

import { compile, IConfiguration } from '@adguard/hostlist-compiler';

After:

import { compile, IConfiguration } from '@jk-com/adblock-compiler';

Types are included—no need for separate @types packages.

Breaking Changes

None! ✨

AdBlock Compiler maintains 100% API compatibility with @adguard/hostlist-compiler. All existing code should work without modifications.

Behavioral Differences

The following improvements are automatic (no code changes needed):

Error Messages - More detailed error messages with error codes
Performance - Faster compilation with parallel source processing
Validation - Enhanced validation with better error reporting
Caching - Automatic caching when deployed as Cloudflare Worker

Testing Your Migration

1. Update Dependencies

# npm
npm uninstall @adguard/hostlist-compiler
npm install @jk-com/adblock-compiler

# Deno
# Just update your import URLs

2. Run Your Tests

npm test
# or
deno test

3. Verify Output

Compile a test filter list and verify the output:

# Should produce identical results
diff old-output.txt new-output.txt

Rollback Plan

If you need to rollback:

# npm
npm uninstall @jk-com/adblock-compiler
npm install @adguard/hostlist-compiler@^1.0.39

# Deno - just revert your imports

Support & Resources

Documentation: docs/api/README.md
Web UI: https://adblock-compiler.jayson-knight.workers.dev/
API Reference: https://adblock-compiler.jayson-knight.workers.dev/api
GitHub Issues: https://github.com/jaypatrick/adblock-compiler/issues
Examples: docs/guides/clients.md

Common Issues

Issue: Package not found

error: JSR package not found: @jk-com/adblock-compiler

Solution: The package needs to be published to JSR first. Use npm import as fallback:

import { compile } from 'npm:@jk-com/adblock-compiler';

Issue: Type errors

Type 'SourceType' is not assignable to type 'SourceType'

Solution: Clear your TypeScript cache and rebuild:

# Deno
rm -rf ~/.cache/deno

# Node
rm -rf node_modules && npm install

Issue: Different output

If the compiled output differs significantly, please file an issue with:

Your configuration file
Expected output vs actual output
Version numbers of both packages

FAQ

Q: Will this break my existing code?

A: No. AdBlock Compiler is designed as a drop-in replacement with 100% API compatibility.

Q: Do I need to change my configuration files?

A: No. All configuration files (JSON, YAML, TOML) work identically.

Q: Can I use both packages simultaneously?

A: Yes, but not recommended. The packages have the same exports and will conflict.

Q: What about performance?

A: AdBlock Compiler is generally faster due to better parallelization and Deno's optimizations.

Q: Is there a migration tool?

A: Not needed! Just update your import statements and you're done.

Q: What if I find a bug?

A: Report it at https://github.com/jaypatrick/adblock-compiler/issues

Success Stories

After migrating, users typically see:

⚡ 30-50% faster compilation times
📉 70-80% reduced cache storage usage
🔄 Zero downtime during migration
✅ 100% test pass rate after migration

Next Steps

✅ Update package dependencies
✅ Update import statements
✅ Run tests
✅ Deploy with confidence!
🎉 Enjoy new features (SSE, batch API, visual diff)

Need help? Open an issue or check the documentation!