uxl-core

library0.1.2jsnpmunverified

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+.

web-framework serialization

npm install uxl-core

package ↗

INSTALL

IMPORT

SIG · UXL-CORE

uxl-core

web-frameworkjavascriptv0.1.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import { parse } from 'uxl-core'

✗ const { parse } = require('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.

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));

Debug

Known issues

breakingESM-only: package does not support CommonJS require(). Using require() throws ERR_REQUIRE_ESM.

fix

Use import syntax or dynamic import().

affects: >=0.1.0

gotchamakeLexer() 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 });

affects: >=0.1.0

gotchatranspile() 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.

affects: >=0.1.0

deprecatedThe '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.

affects: >=0.1.0

gotchastrictIndent: 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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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

fix

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

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

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.

TypeError: transpile is not a function

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

fix

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

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

Empty or incomplete UXL source passed to parse().

fix

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

Upgrade

Version history

0.1.2latest on npm

Audit

Dependencies

nearleyrequiredParser generator runtime for the grammar

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/uxl-core ↗