Monako Lua Builder

Build MonakoOS apps with typed Lua ergonomics and LuaJIT runtime compatibility.

@monako_research/lua-builder lets app developers write .luau source with Luau type annotations, run Luau-powered type checking during development, and emit plain Lua 5.1-compatible code that can run on the MonakoOS LuaJIT runtime.

In short:

.luau app source
  -> type check with luau-analyze
  -> strip Luau type syntax
  -> lower supported syntax
  -> emit LuaJIT-compatible .lua

Why This Exists

MonakoOS uses Lua for app development because it is small, embeddable, and well suited to constrained devices. Plain Lua, however, gives developers limited type safety and weaker editor feedback.

This builder keeps the device runtime simple while improving the developer experience:

• Write app code with typed Lua / Luau syntax.
• Get better IDE and LSP feedback through Luau tooling.
• Catch SDK usage mistakes before shipping.
• Build output that does not require Luau VM support on-device.
• Keep generated code compatible with LuaJIT 2.1 / Lua 5.1.

Features

• monako check runs Monako compatibility checks and luau-analyze.
• monako build emits dist/**/*.lua and dist/monako.package.json.
• monako dev watches source, config, and type files, then rebuilds on change.
• monako clean removes the output directory.
• monako doctor checks local prerequisites.
• monako-strip transforms a single .luau file.
• Parser-based transforms through tree-sitter-luau, not regex replacements.
• Type erasure for local annotations, function annotations, return types, type aliases, export types, and casts.
• Syntax lowering for compound assignment such as count += 1.
• Diagnostics for unsupported continue, Luau runtime-only APIs, and Roblox APIs.

Install

Node.js 20 or newer is required.

Install the builder in a Monako app project:

npm install --save-dev @monako_research/lua-builder

For full checking and builds, install these external tools and make them available on PATH:

• luau-analyze
• luajit

Check your local setup:

npm exec monako -- doctor

The package runs a non-blocking postinstall check. Missing external tools print a warning but do not fail npm install.

Quick Start

Create a minimal project:

my-monako-app/
  src/
    main.luau
  types/
    monako.d.luau
  monako.config.json
  package.json

Add src/main.luau:

--!strict

local monako = require("monako")

type CounterState = {
    count: number,
}

local state: CounterState = {
    count = 0,
}

local function increment()
    state.count += 1
end

return function()
    return monako.ui.column({
        monako.ui.text("Count: " .. tostring(state.count)),
        monako.ui.button({
            text = "Add",
            onClick = increment,
        }),
    })
end

Add monako.config.json:

{
  "name": "hello-monako",
  "entry": "src/main.luau",
  "sourceDir": "src",
  "outDir": "dist",
  "target": "luajit-2.1",
  "strict": true,
  "types": ["types/monako.d.luau"],
  "compilerOptions": {
    "stripTypes": true,
    "lowerCompoundAssignment": true,
    "disallowContinue": true,
    "disallowLuauRuntimeApis": true,
    "disallowRobloxApis": true,
    "luaVersion": "5.1"
  }
}

Run checks and build:

npm exec monako -- check
npm exec monako -- build

The generated Lua will look like:

local monako = require("monako")

local state = {
    count = 0,
}

local function increment()
    state.count = state.count + 1
end

return function()
    return monako.ui.column({
        monako.ui.text("Count: " .. tostring(state.count)),
        monako.ui.button({
            text = "Add",
            onClick = increment,
        }),
    })
end

Commands

npm exec monako -- doctor
npm exec monako -- check
npm exec monako -- build
npm exec monako -- dev
npm exec monako -- clean

Single-file transform:

npm exec monako-strip -- src/main.luau -o /tmp/main.lua

Build flags:

npm exec monako -- build --no-check
npm exec monako -- build --no-luajit-check

Use these flags mainly for debugging. A normal production build should run both Luau type checking and LuaJIT syntax checking.

Tool Paths

If luau-analyze or luajit are not on PATH, configure explicit paths:

{
  "tools": {
    "luauAnalyze": "/path/to/luau-analyze",
    "luajit": "/path/to/luajit"
  }
}

Temporary environment overrides are also supported:

LUAU_ANALYZE=/path/to/luau-analyze LUAJIT=/path/to/luajit npm exec monako -- build

Project Template

This repository includes a basic template:

templates/basic/
  src/main.luau
  types/monako.d.luau
  monako.config.json

Copy it into a separate app project, install the npm package, then run:

npm exec monako -- check
npm exec monako -- build

Output And Constraints

Generated output targets:

• LuaJIT 2.1
• Lua 5.1-compatible syntax
• no Luau VM dependency
• no Roblox runtime dependency

The first version intentionally supports a focused language subset. It strips type syntax and lowers known compatible syntax, but it is not a full Luau runtime or a general Luau-to-Lua compiler.

Unsupported or blocked patterns include:

• continue
• Roblox globals such as game, Instance, and Vector3
• Luau runtime-only APIs such as table.freeze, table.clone, math.clamp, string.split, and typeof
• Lua syntax or standard library behavior that is incompatible with LuaJIT / Lua 5.1

Development

For contributors working on this builder:

npm install
npm run build
npm test

When adding compiler behavior, add focused tests under test/. Keep transforms parser-driven; do not implement type stripping with ad hoc regex replacement.