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

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.

• 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<string, any>)
• Function types ((x: number) -> string → (x: number) => string)
• Union types ("GET" | "POST" → "GET" | "POST")
• Method types with automatic self parameter 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

# Using bun bun add luats # Using npm npm install luats # Using yarn yarn add luats

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<string, number>; }

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] );

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);

• 🎮 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:

• Getting Started Guide
• API Reference
• CLI Usage
• Plugin System
• Examples
• Contributing Guide

# 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 --watch

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"] }

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}`; } };

LuaTS features a modular architecture:

• src/parsers/ - Lua and Luau parsers with AST generation
• src/clients/ - Lexer and formatter with component-based design
• src/generators/ - TypeScript and Markdown generators
• src/plugins/ - Plugin system with transformation hooks
• src/cli/ - Command-line interface with configuration support
• src/types.ts - Comprehensive AST type definitions

Contributions are welcome! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.