{"id":26577,"library":"uxl-core","title":"UXL Core","description":"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+.","status":"active","version":"0.1.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install uxl-core","lang":"bash","label":"npm"},{"cmd":"yarn add uxl-core","lang":"bash","label":"yarn"},{"cmd":"pnpm add uxl-core","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Parser generator runtime for the grammar","package":"nearley","optional":false}],"imports":[{"note":"ESM-only package; CommonJS require() will fail.","wrong":"const { parse } = require('uxl-core')","symbol":"parse","correct":"import { parse } from 'uxl-core'"},{"symbol":"makeLexer","correct":"import { makeLexer } from 'uxl-core'"},{"note":"Transpiles AST to contract.json; for full project resolution, use uxl-kit.","symbol":"transpile","correct":"import { transpile } from 'uxl-core'"}],"quickstart":{"code":"import { parse, makeLexer, transpile } from 'uxl-core';\n\nconst source = `\ndata cart:\n  inline:\n    items:\n      id: \"p1\", title: \"T-Shirt\", price: 25.0, qty: 2\n    total: 50.0\n`;\n\n// Parse a single UXL file to AST\nconst ast = parse(source, { trace: false });\n\n// Transpile AST to contract (partial for single file)\nconst contract = transpile(ast);\n\nconsole.log(JSON.stringify(ast, null, 2));\nconsole.log(JSON.stringify(contract, null, 2));","lang":"typescript","description":"Parses UXL source and transpiles to contract.json."},"warnings":[{"fix":"Use import syntax or dynamic import().","message":"ESM-only: package does not support CommonJS require(). Using require() throws ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"const lexer = makeLexer({ baseIndent: 4 });","message":"makeLexer() options: baseIndent default is 2, not 4. If your UXL uses 4-space indentation, you must pass baseIndent: 4 to avoid parse errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use uxl-kit to resolve multi-file projects before transpiling.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set trace: false or omit.","message":"The 'trace' option in parse() is experimental and may change behavior in future versions. Relying on its output is not recommended.","severity":"deprecated","affected_versions":">=0.1.0"},{"fix":"Set strictIndent: false or ensure consistent indentation.","message":"strictIndent: true enforces that every indentation level is a multiple of baseIndent. If your file uses mixed indentation, parsing will fail.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Change to import syntax: import { parse } from 'uxl-core';","cause":"uxl-core is ESM-only and cannot be imported via require().","error":"ERR_REQUIRE_ESM: require() of ES Module /path/to/uxl-core/index.js from /path/to/file.js not supported."},{"fix":"Adjust makeLexer({ baseIndent: <actual_indent> }) or fix indentation in the UXL file.","cause":"Indentation mismatch: the lexer's baseIndent or strictIndent settings do not match the file's indentation.","error":"SyntaxError: Unexpected token at line X, column Y — expected indentation of Z spaces but found W"},{"fix":"Use import { transpile } from 'uxl-core';","cause":"Transpile not imported correctly; possible CommonJS usage or wrong import name.","error":"TypeError: transpile is not a function"},{"fix":"Ensure the source string contains valid UXL syntax with at least one top-level definition.","cause":"Empty or incomplete UXL source passed to parse().","error":"Error: nearley: syntax error at line 1 (no token context) — unexpected EOF"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}