ZeroTier Rule Compiler

1.2.2-2 verified Fri May 01 auth: no javascript

A tool to compile human-readable ZeroTier rule scripts into the binary format required by ZeroTier network controllers. Current stable version is 1.2.2-2. This package is part of the ZeroTier ecosystem and is used internally by ZeroTier Central's rules editor. It provides both a library API and a CLI interface. Unlike manual rule construction, this compiler validates syntax and ensures correct encoding. The package is available on npm and has minimal dependencies. Release cadence is irregular, tied to ZeroTierOne updates.

Common errors

error SyntaxError: Unexpected token at line 3: 'accept' ↓

cause Rule scripts require line breaks or semicolons between statements; missing newline.

fix

Ensure each rule statement is on its own line or separated by semicolons.

error TypeError: compile is not a function ↓

cause Using CommonJS require instead of ESM import; package is ESM-only.

fix

Use 'import' syntax, or if using Node <13, set 'type': 'module' in package.json.

error RangeError: Rule length exceeds 4096 bytes ↓

cause Compiled rule set too large for ZeroTier network controller limit.

fix

Optimize rules by reducing complexity or combining conditions.

Warnings

gotcha The compile function throws on invalid syntax; always use try/catch. ↓

fix Wrap calls to compile in try/catch blocks.

deprecated The CLI script cli.js uses synchronous file reading; may block event loop on large files. ↓

fix Use the programmatic API with async I/O for large scripts.

breaking Versions prior to 1.0.0 used a different AST representation; compatibility broken. ↓

fix Upgrade to >=1.0.0 and update imports to ESM.

Install

npm install zerotier-rule-compiler

yarn add zerotier-rule-compiler

pnpm add zerotier-rule-compiler

Imports

compile

wrong

const compile = require('zerotier-rule-compiler').compile

correct

import { compile } from 'zerotier-rule-compiler'

ESM-only since v1.0.0, no CJS support.

stringify

wrong

import { stringify } from 'zerotier-rule-compiler' (no common mistake)

correct

import { stringify } from 'zerotier-rule-compiler'

Utility to convert binary rules back to human-readable format.

parseError

wrong

const parseError = require('zerotier-rule-compiler').parseError

correct

import { parseError } from 'zerotier-rule-compiler'

Type error for debugging rule compilation failures.

Quickstart

Compiles a simple ZeroTier rule script and then stringifies the result back to human-readable format.

import { compile, stringify } from 'zerotier-rule-compiler';
const script = `# accept all traffic on VLAN 1
drop
accept`;
try {
  const binaryRules = compile(script);
  console.log('Binary rules:', binaryRules);
  const reString = stringify(binaryRules);
  console.log('Stringified:', reString);
} catch (err) {
  console.error('Compilation error:', err);
}