JSX Lua Transpiler

1.1.2 verified Fri May 01 auth: no javascript

A TypeScript library (v1.1.2) that transpiles JSX-like syntax into Lua tables. It parses JSX expressions embedded in Lua code and converts them to a structured table format with type, name, atts (attributes), and children fields. This enables writing HTML-like markup inside Lua, particularly useful for Lua-based UI frameworks or game engines. The package ships TypeScript declarations and requires TypeScript 5+ as a peer dependency. Compared to general Lua transpilers, it is focused specifically on JSX-to-Lua conversion with no overhead. The project is maintained by a single developer on GitHub.

Common errors

error Cannot find module 'jsx-lua-transpiler' or its corresponding type declarations ↓

cause Missing TypeScript peer dependency or not installed.

fix

Run 'npm install typescript@^5' as a dev dependency.

error Expected a assignment or function call and instead saw an expression ↓

cause Trying to use JSX outside of Lua code string assignment.

fix

Wrap JSX in a Lua string and pass to transpileLuaX.

error TypeError: transpileLuaX is not a function ↓

cause Importing default export instead of named export.

fix

Use 'import { transpileLuaX } from 'jsx-lua-transpiler''.

Warnings

breaking v1.0.0 changed output table structure: children now always an array, not table with numeric indices. ↓

fix Update code expecting old format; adjust Lua code that processes the transpiled tables.

gotcha JSX must be written as literal in Lua string; strings containing JSX are not transpiled. ↓

fix Ensure JSX is not inside a Lua string literal. Use raw code blocks.

gotcha Self-closing tags (like <img />) require the trailing slash; otherwise parsed incorrectly. ↓

fix Always close self-closing tags with />.

deprecated transpileLuaX function behavior changed in v1.1.0: now returns an object with 'code' field. ↓

fix Update to v1.1.0+ and access output.code instead of plain string.

gotcha HTML tag attributes with hyphens (e.g., data-value) may not be recognized; use camelCase or quoted strings. ↓

fix Use attribute names without hyphens or wrap in quotes if needed.

Install

npm install jsx-lua-transpiler

yarn add jsx-lua-transpiler

pnpm add jsx-lua-transpiler

Imports

transpileLuaX

wrong

const transpileLuaX = require('jsx-lua-transpiler')

correct

import { transpileLuaX } from 'jsx-lua-transpiler'

The package is ESM-only (TypeScript source). Default export not available.

TranspileResult

wrong

import { TranspileResult } from 'jsx-lua-transpiler'

correct

import type { TranspileResult } from 'jsx-lua-transpiler'

TranspileResult is a type, use 'import type' to avoid runtime import.

default

wrong

import transpileLuaX from 'jsx-lua-transpiler'

correct

import { transpileLuaX } from 'jsx-lua-transpiler'

No default export; only named export exists.

Quickstart

Demonstrates converting JSX-like syntax within Lua code into a nested Lua table representation using transpileLuaX.

import { transpileLuaX } from 'jsx-lua-transpiler';

const luaCode = `
local element = <div class="container">
    <h1>Hello World</h1>
    <img src="image.jpg" alt="An image" />
</div>

print(element)
`;

const transpiled = transpileLuaX(luaCode);
console.log(transpiled);
// Output: {
//   type: 'html', name: 'div', atts: { class: 'container' },
//   children: [
//     { type: 'html', name: 'h1', atts: {}, children: [{ type: 'text', text: 'Hello World' }] },
//     { type: 'html', name: 'img', atts: { src: 'image.jpg', alt: 'An image' }, children: [] }
//   ]
// }