FreeScript
LuaTS
by CodeMeAPixel · version 2026.01.21 · updated 3 days ago
No reviews yet
- Downloads
- 0
- Reviews
- 0
- Size
- 841 KB
- Code check
- Checked
- Licence
- MIT
- Released
- Nov 2026
A TypeScript library for parsing, formatting, and providing type interfaces for Lua and Luau code.
A TypeScript library for parsing, formatting, and providing type interfaces for Lua and Luau code.
Explore the docs »
View Examples
·
Report Bug
·
Request Feature
·
Security
·
Contributing
🌟 What is LuaTS?
LuaTS bridges the gap between Lua/Luau and TypeScript ecosystems, allowing developers to leverage type safety while working with Lua codebases. Whether you're developing Roblox games, working with embedded Lua, or maintaining legacy Lua code, LuaTS helps you generate accurate TypeScript definitions for better IDE support, type checking, and developer experience.
✨ Features🔁 Core Parsing & Generation****
📦 Installation
🚀 Quick StartBasic Type Generation
Output:
Advanced Usage with Plugins
Parsing and Formatting
💡 Use Cases
Visit luats.lol for comprehensive documentation including: 🛠 CLI UsageBasic Commands
Configuration File
Create
🧩 Plugin System
Create custom plugins to extend LuaTS functionality:
🏗️ Architecture
LuaTS f
…
Explore the docs »
View Examples
·
Report Bug
·
Request Feature
·
Security
·
Contributing
🌟 What is LuaTS?
LuaTS bridges the gap between Lua/Luau and TypeScript ecosystems, allowing developers to leverage type safety while working with Lua codebases. Whether you're developing Roblox games, working with embedded Lua, or maintaining legacy Lua code, LuaTS helps you generate accurate TypeScript definitions for better IDE support, type checking, and developer experience.
✨ Features🔁 Core Parsing & Generation****
- Parse standard Lua and Luau code into Abstract Syntax Trees (AST)
- Convert Luau type declarations into TypeScript interfaces
- Format Lua/Luau code with customizable styling options
- Comprehensive AST manipulation with full type definitions
- Maps Lua types to TypeScript equivalents (
string,number,boolean,nil→null) - Optional types (
foo: string?→foo?: string) - Array types (
{string}→string[]) - Record types (
{[string]: any}→Record) - Function types (
(x: number) -> string→(x: number) => string) - Union types (
"GET" | "POST"→"GET" | "POST") - Method types with automatic
selfparameter removal
- Template string interpolation with backtick support
- Continue statements with proper loop context validation
- Reserved keywords as property names (
type,export,function,local) - Comment preservation and JSDoc conversion
- Multi-line comment support (
--[[ ]]→/** */)
- Component-based lexer system with specialized tokenizers
- Plugin system for custom type transformations
- Extensible tokenizer architecture for easy feature additions
- Clean separation of concerns across all modules
- CLI tool with file watching and batch processing
- Configuration file support (
luats.config.json) - Programmatic API with comprehensive options
- Error handling and validation with detailed diagnostics
**Convert single files**
luats convert file.lua -o file.d.ts
**Batch process directories**
luats convert-dir src/lua -o src/types
**Watch mode for development**
luats convert-dir src/lua -o src/types --watch
**Validate syntax**
luats validate file.lua📦 Installation
**Using bun**
bun add luats
**Using npm**
npm install luats
**Using yarn**
yarn add luats🚀 Quick StartBasic Type Generation
import { generateTypes } from 'luats';
const luauCode = `
type Vector3 = {
x: number,
y: number,
z: number
}
type Player = {
name: string,
position: Vector3,
health: number,
inventory?: {[string]: number}
}
`;
const tsCode = generateTypes(luauCode);
console.log(tsCode);Output:
interface Vector3 {
x: number;
y: number;
z: number;
}
interface Player {
name: string;
position: Vector3;
health: number;
inventory?: Record;
}Advanced Usage with Plugins
import { generateTypesWithPlugins } from 'luats';
const customPlugin = {
name: 'ReadonlyPlugin',
description: 'Makes all properties readonly',
transformType: (luauType, tsType) => tsType,
postProcess: (code) => code.replace(/(\w+):/g, 'readonly $1:')
};
const tsCode = await generateTypesWithPlugins(
luauCode,
{ useUnknown: true },
[customPlugin]
);Parsing and Formatting
import { parseLuau, formatLua, LuaFormatter } from 'luats';
// Parse Luau code
const ast = parseLuau(`
local function greet(name: string): string
return "Hello, " .. name
end
`);
// Format with custom options
const formatter = new LuaFormatter({
indentSize: 4,
insertSpaceAroundOperators: true
});
const formatted = formatter.format(ast);💡 Use Cases
- 🎮 Roblox Development: Generate TypeScript definitions from Luau types for better IDE support
- 🎯 Game Development: Maintain type safety when interfacing with Lua-based game engines
- 📚 Legacy Code Integration: Add TypeScript types to existing Lua codebases
- 🔌 API Type Definitions: Generate TypeScript types for Lua APIs
- 🛠️ Development Tools: Build better tooling for Lua/TypeScript interoperability
Visit luats.lol for comprehensive documentation including: 🛠 CLI UsageBasic Commands
**Convert a single file**
npx luats convert src/player.lua -o src/player.d.ts
**Convert a directory**
npx luats convert-dir src/lua -o src/types
**Validate syntax**
npx luats validate src/player.lua
**Watch for changes**
npx luats convert-dir src/lua -o src/types --watchConfiguration File
Create
luats.config.json:
{
"outDir": "./types",
"include": ["**/*.lua", "**/*.luau"],
"exclude": ["**/node_modules/**"],
"preserveComments": true,
"commentStyle": "jsdoc",
"typeGeneratorOptions": {
"useUnknown": true,
"interfacePrefix": "",
"includeSemicolons": true
},
"plugins": ["./plugins/my-plugin.js"]
}🧩 Plugin System
Create custom plugins to extend LuaTS functionality:
import { Plugin } from 'luats';
const MyPlugin: Plugin = {
name: 'MyPlugin',
description: 'Custom type transformations',
transformType: (luauType, tsType) => {
if (tsType === 'number') return 'SafeNumber';
return tsType;
},
postProcess: (code) => {
return `// Generated with MyPlugin\n${code}`;
}
};🏗️ Architecture
LuaTS f
…