avdl-compiler

1.4.10 verified Fri May 01 auth: no javascript

AVDL (Avro IDL) compiler that generates Go, Python, and TypeScript source code from protocol definition files. Current stable version is 1.4.10, released infrequently as a Keybase internal tool. Key differentiators: supports multi-language output (Go, Python, TypeScript) from a single AVDL schema, implements the Avro interface description language, and is written in IcedCoffeeScript. Compared to other Avro tools like avro-tools or avrodoc, this compiler is specifically designed for generating bot SDK code across Keybase's supported languages.

Common errors

error Error: Cannot find module 'iced-coffee-script' ↓

cause Missing iced-coffee-script dependency.

fix

Install required peer dependency: npm install iced-coffee-script

error TypeError: compileFile is not a function ↓

cause Importing the package incorrectly; compileFile is a named export.

fix

Use const { compileFile } = require('avdl-compiler'); not const compileFile = require('avdl-compiler');

error SyntaxError: Unexpected token on line 1 of AVDL file ↓

cause Invalid AVDL syntax, possibly missing protocol declaration.

fix

Ensure AVDL starts with 'protocol ProtocolName {' and follows Avro IDL syntax.

Warnings

gotcha The compiler requires IcedCoffeeScript, which might conflict with other CoffeeScript versions in your project. ↓

fix Use a separate Node environment or containerize your build.

deprecated The Python code generation might be incomplete or experimental. ↓

fix Prefer Go or TypeScript output for production use.

breaking Output format can change between minor versions without notice. ↓

fix Pin to a specific version in your package.json.

gotcha Only supports a subset of Avro schema features (e.g., no unions with null). ↓

fix Check the AVDL specification against supported schema features.

gotcha The compiler is written in IcedCoffeeScript, which is an unmaintained fork of CoffeeScript. ↓

fix There is no fix; consider migrating to a different Avro compiler.

Install

npm install avdl-compiler

yarn add avdl-compiler

pnpm add avdl-compiler

Imports

default

wrong

import compile from 'avdl-compiler'

correct

const compile = require('avdl-compiler')

Package is CommonJS only; ESM import is not supported.

compileFile

wrong

import { compileFile } from 'avdl-compiler'

correct

const { compileFile } = require('avdl-compiler')

Named export available via require; ESM not supported.

compileString

const { compileString } = require('avdl-compiler')

Compiles AVDL from a string variable.

CompileOptions
```
const { CompileOptions } = require('avdl-compiler')
```
TypeScript interface; use with JSDoc or TypeScript types.

Quickstart

Compiles an AVDL file to Go using compileFile and shows the output.

const { compileFile } = require('avdl-compiler');
const fs = require('fs');

// Example AVDL content: protocol Example { record Person { string name; int age; } }
const avdlContent = `protocol Example {
  record Person {
    string name;
    int age;
  }
}`;

fs.writeFileSync('example.avdl', avdlContent);

const options = {
  language: 'go',
  packageName: 'main',
  namespace: 'com.example',
};

const result = compileFile('example.avdl', options);
console.log(result);
// Output: Go code representing the Person record

fs.unlinkSync('example.avdl');