@eryx/luau ModuleLuau source code parser, compiler, and type checker.
Parses Luau source into a structured AST (Abstract Syntax Tree) with full type-safety. Also provides bytecode compilation, loading, native JIT compilation, bytecode disassembly, full type checking, type inference at positions, and autocompletion.
Every node carries a type discriminator string and a location with
1-based line/column positions.
local luau = require("@eryx/luau")
local result = luau.parse(source, { captureComments = true })
for _, stat in result.root.body do
print(stat.type, stat.location.start.line)
end
-- Type check a file
local checked = luau.check(source, { mode = "strict", annotate = true })
print(checked.annotated) -- source with type annotations
-- Query a type at a position
local ty = luau.typeAt(source, 1, 7)
print(ty) -- e.g. "number"
Parses Luau source code and returns a structured AST.
The returned root is a Block node whose body contains an array
of statement nodes. Every node carries a type string discriminator
and a location with 1-based line/column positions.
Pass { captureComments = true } to include a comments array in
the result.
local result = luau.parse(source, { captureComments = true })
print("Lines:", result.lines)
print("Errors:", #result.errors)
print("Top-level statements:", #result.root.body)
The Luau source code string to parse.
Parse options (e.g. comment capture).
The parse result containing the AST root, errors, and optional comments.
Pretty-prints Luau source code by round-tripping through the parser.
The Luau source code to format.
The reformatted source code.
Compiles Luau source code to bytecode.
The returned bytecode blob can be passed to load or cached for later use. If the source has syntax errors the bytecode will contain an encoded error that load will surface.
local bytecode = luau.compile(source, { optimizationLevel = 2 })
local fn = luau.load(bytecode, "=cached")
fn()
The Luau source code to compile.
Compiler options (optimization, debug, coverage levels).
The compiled bytecode blob.
Loads Luau source code or pre-compiled bytecode as a callable function.
Accepts either a source string (which will be compiled automatically)
or a bytecode blob previously returned by compile. This is the
equivalent of loadstring in standard Lua.
local fn = luau.load("return 1 + 2", "=example")
print(fn()) -- 3
Luau source code or compiled bytecode.
Optional name for the chunk (shown in errors/stack traces, defaults to "=load").
The loaded function.
Returns a human-readable bytecode listing for the given source.
Compiles the source and returns a formatted disassembly string showing every function's bytecode instructions, optionally with source lines, local variable info, compiler remarks, and type annotations.
local listing = luau.disassemble(source, {
showLocals = true,
showRemarks = true,
})
print(listing)
The Luau source code to disassemble.
Disassembly options controlling output detail.
The formatted bytecode listing.
Runs the Luau type checker on a source string.
Returns a CheckResult containing any type errors found. When
options.annotate is true, also returns the source code rewritten
with inferred type annotations attached to every binding and
expression. The result also includes built-in Luau lints under
result.lints.
local result = luau.check(source, { mode = "strict", annotate = true })
for _, err in result.errors do
print(err.message, err.location.start.line)
end
if result.annotated then
print(result.annotated)
end
The Luau source code to type-check.
Type-checking options.
The type-check result.
Infers the type at a specific position in Luau source code.
Runs the type checker in strict mode (by default) and queries the inferred type at the given 1-based line and column. Useful for building LSP hover information or type inspection tools.
Returns nil if no type can be determined at that position (e.g.
whitespace, comments, or if the position is out of range).
local source = "local x = 42\nprint(x)"
local ty = luau.typeAt(source, 1, 7) -- position of 'x'
print(ty) -- "number"
The Luau source code.
1-based line number.
1-based column number.
Type inference options.
The inferred type as a string, or nil.
Computes autocompletion entries at a cursor position.
Runs type checking and returns contextual completions, including property names, local bindings, keywords, and types - along with their inferred types where available. This is the same engine used by Luau language servers.
local source = 'local t = {foo = 1, bar = "hi"}\nt.'
local result = luau.autocomplete(source, 2, 3) -- after "t."
for name, entry in result.entries do
print(name, entry.kind, entry.type)
end
-- foo Property number
-- bar Property string
The Luau source code.
1-based line number of the cursor.
1-based column number of the cursor.
Autocomplete options.
The autocomplete result.
Resolve a require() path relative to a source file.
Given the absolute path of a Luau source file and a require string
(relative path like "./foo", "../bar", or alias path like
"@alias/mod"), returns the absolute path to the resolved module
file, or nil if no matching file was found.
Uses the same resolution rules as the type checker:
.luau -> .lua -> dir/init.luau -> dir/init.lua.luaurc files walking up the directory tree.init.luau files resolve relative requires from the parent directory.local target = luau.resolve("C:/project/src/main.luau", "./utils")
print(target) -- "C:\\project\\src\\utils.luau"
Absolute path of the source file containing the require.
The require string to resolve.
Absolute path to the resolved file, or nil.
A position in source code (1-based line and column).
A comment descriptor. Only present when captureComments is enabled
in the ParseOptions.
Union of all type annotation nodes.
Union of all type-pack nodes (used for return types and variadic packs).
Union of all expression nodes.
Union of all statement nodes.
Any AST node (statement, expression, or type annotation).
Options for compile.
Options for disassemble.
A definition source for loading type definitions.
Can be a plain string (the definition source text) or a table with
a source field and optional name (package name, e.g. "@mygame").
Options for check
Type-checking mode: "strict" for full checking, "nonstrict" (default)
for lenient checking, "nocheck" for no type checking.
If true, the result includes an annotated field with the source
rewritten to include inferred type annotations.
Additional type definition sources to load before type checking.
These are .d.luau-style definition strings that declare global
types and functions available in the checked source.
Absolute file path of the source being checked. When provided,
require() calls in the source are resolved relative to this path,
and .luaurc alias configs are discovered by walking up from it.
A type error from the type checker.
Human-readable error message.
Source location of the error.
Error category: "TypeError" or "SyntaxError".
A lint diagnostic produced by Luau's built-in linter.
Lint severity category.
Numeric lint code.
Stable lint code name (for example "LocalUnused").
Human-readable lint message.
Source location for the lint.
Lint diagnostics grouped by severity plus flattened ordering.
The result returned by check.
Type errors found during checking (empty array if none).
Built-in Luau lint diagnostics for this source.
The source code with inferred type annotations attached.
Only present when options.annotate is true.
Options for typeAt.
Type-checking mode. Defaults to "strict" for best inference.
Additional type definition sources to load before inference.
Absolute file path of the source. Enables require() resolution.
If true, return a structured type object instead of just a string.
Options for autocomplete.
Type-checking mode. Defaults to "strict" for best results.
Additional type definition sources to load before completion.
Absolute file path of the source. Enables require() resolution.
If true, include typeDetail for each typed autocomplete entry.
An autocompletion entry.
What kind of completion this is.
The inferred type of this entry (absent for keywords).
Structured type metadata (when options.detailed is true).
Whether this entry is deprecated.
Whether this entry's type matches what's expected at the cursor.
Suggested text to insert.
Parentheses recommendation: "CursorAfter" means add () with
cursor after, "CursorInside" means add () with cursor between.
The result returned by autocomplete.
The autocomplete context at the cursor position.
Map of completion name to entry details.