UXL Core

0.1.2 verified Fri May 01 auth: no javascript

Core parser, lexer, and transpiler for the UXL (User eXperience Lab / UXer eXperiment Language) framework. Current stable version 0.1.2. Designed for defining UI screens, data bindings, i18n, A/B tests, and component trees in a declarative DSL. The library provides an indentation-aware lexer (with configurable tab width and strict indentation enforcement), a Nearley-based parser that converts UXL source into an AST, and a transpiler that converts the AST into a stable contract.json format for downstream renderers. Unlike full-stack frameworks, uxl-core focuses on the parsing layer; multi-file project resolution and CLI are handled by the companion package uxl-kit. It is ESM-only and requires Node.js 18+.

Common errors

error ERR_REQUIRE_ESM: require() of ES Module /path/to/uxl-core/index.js from /path/to/file.js not supported. ↓

cause uxl-core is ESM-only and cannot be imported via require().

fix

Change to import syntax: import { parse } from 'uxl-core';

error SyntaxError: Unexpected token at line X, column Y — expected indentation of Z spaces but found W ↓

cause Indentation mismatch: the lexer's baseIndent or strictIndent settings do not match the file's indentation.

fix

Adjust makeLexer({ baseIndent: <actual_indent> }) or fix indentation in the UXL file.

error TypeError: transpile is not a function ↓

cause Transpile not imported correctly; possible CommonJS usage or wrong import name.

fix

Use import { transpile } from 'uxl-core';

error Error: nearley: syntax error at line 1 (no token context) — unexpected EOF ↓

cause Empty or incomplete UXL source passed to parse().

fix

Ensure the source string contains valid UXL syntax with at least one top-level definition.

Warnings

breaking ESM-only: package does not support CommonJS require(). Using require() throws ERR_REQUIRE_ESM. ↓

fix Use import syntax or dynamic import().

gotcha makeLexer() options: baseIndent default is 2, not 4. If your UXL uses 4-space indentation, you must pass baseIndent: 4 to avoid parse errors. ↓

fix const lexer = makeLexer({ baseIndent: 4 });

gotcha transpile() expects a complete AST from a full project. Running on a single file produces a partial contract that may be missing top-level definitions (SCREEN, DATA, etc.) unless all are in that file. ↓

fix Use uxl-kit to resolve multi-file projects before transpiling.

deprecated The 'trace' option in parse() is experimental and may change behavior in future versions. Relying on its output is not recommended. ↓

fix Set trace: false or omit.

gotcha strictIndent: true enforces that every indentation level is a multiple of baseIndent. If your file uses mixed indentation, parsing will fail. ↓

fix Set strictIndent: false or ensure consistent indentation.

Install

npm install uxl-core

yarn add uxl-core

pnpm add uxl-core

Imports

parse

wrong

const { parse } = require('uxl-core')

correct

import { parse } from 'uxl-core'

ESM-only package; CommonJS require() will fail.

makeLexer
```
import { makeLexer } from 'uxl-core'
```
transpile
```
import { transpile } from 'uxl-core'
```
Transpiles AST to contract.json; for full project resolution, use uxl-kit.

Quickstart

Parses UXL source and transpiles to contract.json.

import { parse, makeLexer, transpile } from 'uxl-core';

const source = `
data cart:
  inline:
    items:
      id: "p1", title: "T-Shirt", price: 25.0, qty: 2
    total: 50.0
`;

// Parse a single UXL file to AST
const ast = parse(source, { trace: false });

// Transpile AST to contract (partial for single file)
const contract = transpile(ast);

console.log(JSON.stringify(ast, null, 2));
console.log(JSON.stringify(contract, null, 2));