Idyll Compiler

5.0.0-alpha.2 verified Fri May 01 auth: no javascript

Lexer and parser for the Idyll markup language, converting Idyll source into an abstract syntax tree (AST). Current version is 5.0.0-alpha.2, with active development. It allows embedding Idyll documents in web pages when combined with idyll-document. Key differentiators: provides a full AST for custom processing, supports async compilation, and is part of the Idyll ecosystem. It is ESM-only and requires Node.js 12+.

Common errors

error SyntaxError: Unexpected token ↓

cause Idyll syntax error in input string (e.g., mismatched tags).

fix

Validate your Idyll syntax. Use an Idyll linter or check brackets.

error compiler is not a function ↓

cause Importing the package incorrectly (CJS vs ESM).

fix

Use import { compile } from 'idyll-compiler'.

error Cannot find module 'idyll-compiler' ↓

cause Package not installed or incorrect version.

fix

Run npm install idyll-compiler and ensure it's in dependencies.

Warnings

breaking v5 changed from CJS to ESM only. ↓

fix Use import syntax and ensure your project supports ESM ("type": "module" in package.json).

deprecated compile callback style removed in v5; use Promise-based API. ↓

fix Use .then/catch or async/await instead of callback.

gotcha For browser usage, compile runs synchronously if options.async is false. ↓

fix Set { async: false } to avoid Webpack issues with dynamic imports.

Install

npm install idyll-compiler

yarn add idyll-compiler

pnpm add idyll-compiler

Imports

compile

wrong

const compile = require('idyll-compiler')

correct

import { compile } from 'idyll-compiler'

ESM-only; CommonJS require will fail. Use the named export.

preprocess
```
import { preprocess } from 'idyll-compiler'
```
Available if you need to preprocess Idyll source before full compilation.
default export
wrong
```
import { default } from 'idyll-compiler'
```
correct
```
import idyllCompiler from 'idyll-compiler'
```
The module has a default export that is the compile function. Prefer named import for clarity.

Quickstart

Compiles a simple Idyll string with variable and inline element into an AST, then logs it.

import { compile } from 'idyll-compiler';

const input = `[var name:"World"]\nHello [span]${name}[/span]!`;

compile(input, { async: false }).then(ast => {
  console.log(JSON.stringify(ast, null, 2));
}).catch(err => {
  console.error(err);
});