{"id":26320,"library":"roblox-ts","title":"roblox-ts","description":"roblox-ts is a TypeScript-to-Luau compiler that enables writing Roblox games using TypeScript syntax and tooling. Current stable version is 3.0.0, with active development and regular releases (major/minor every few months). Key differentiators: full support for TypeScript features (generics, JSX, async/await), macros for compile-time optimizations, and seamless integration with Roblox's object model. Unlike alternatives like Luau or bare Lua, roblox-ts provides type safety, IDE support, and modern language features while compiling to efficient Luau code.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/roblox-ts/roblox-ts","tags":["javascript","typescript"],"install":[{"cmd":"npm install roblox-ts","lang":"bash","label":"npm"},{"cmd":"yarn add roblox-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add roblox-ts","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for TypeScript language services and compilation pipeline","package":"typescript","optional":false},{"reason":"Provides type definitions for Roblox APIs","package":"@rbxts/compiler-types","optional":false}],"imports":[{"note":"ESM-only since v2. Import from 'rbxtsc' (not 'roblox-ts').","wrong":"const Compiler = require('rbxtsc').Compiler","symbol":"Compiler","correct":"import { Compiler } from 'rbxtsc'"},{"note":"Default export is the Compiler class. Use named import for clarity.","wrong":"const robloxTs = require('rbxtsc')","symbol":"default","correct":"import robloxTs from 'rbxtsc'"},{"note":"Use type-only import if you only need the type, to avoid code generation.","wrong":"import { ProjectInfo } from 'rbxtsc'","symbol":"ProjectInfo","correct":"import type { ProjectInfo } from 'rbxtsc'"},{"note":"Both work, but destructuring is preferred in CJS.","wrong":"const ProjectInfo = require('rbxtsc').ProjectInfo","symbol":"ProjectInfo","correct":"const { ProjectInfo } = require('rbxtsc')"},{"note":"Part of roblox-ts, not a separate package.","wrong":"import { TSConfigReader } from 'tsconfig-reader'","symbol":"TSConfigReader","correct":"import { TSConfigReader } from 'rbxtsc'"}],"quickstart":{"code":"import { Compiler } from 'rbxtsc';\n\nconst compiler = new Compiler({\n  project: 'tsconfig.json',\n  rojoConfig: 'default.project.json',\n  optimizedLoops: true,\n  writeTransformedFiles: true,\n  plugins: [],\n});\n\ncompiler.compile().then((result) => {\n  if (result.success) {\n    console.log('Compilation succeeded!');\n  } else {\n    console.error('Compilation failed:', result.errors);\n  }\n});","lang":"typescript","description":"Shows how to programmatically invoke the compiler with configuration options."},"warnings":[{"fix":"Upgrade Node.js to 18 or later.","message":"v3 removed support for Node 14; requires Node 18+.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use `npx create-roblox-ts` or `npm create roblox-ts` to scaffold projects.","message":"v2.3.0 removed `rbxtsc init` command in favor of `npm create roblox-ts`.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Remove the flag or set `--optimizedLoops=false` to disable.","message":"Using `--optimizedLoops` flag is now enabled by default in v3; explicit flag is deprecated.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Wrap `@rbxts` scope in a folder and list other scopes as needed.","message":"In `default.project.json`, node_modules scopes must be explicitly listed (since v2.0.1).","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Use a custom map or `@rbxts/string-enum-utils` for reverse mapping.","message":"Enum inverse mapping for string values removed in v2.3.0; string enums no longer support reverse lookup.","severity":"gotcha","affected_versions":">=2.3.0"},{"fix":"Use getters/setters with explicit `get` and `set` syntax.","message":"TypeScript `accessor` keyword is not supported and will produce a diagnostic.","severity":"gotcha","affected_versions":">=2.1.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install with `npm install -D rbxtsc` and import from 'rbxtsc'.","cause":"Package not installed or wrong import path (some users try 'roblox-ts' instead of 'rbxtsc').","error":"Error: Cannot find module 'rbxtsc'"},{"fix":"Install with `npm install -D @rbxts/compiler-types` and add to tsconfig.json `types`.","cause":"Missing type definitions package for Roblox APIs.","error":"error TS2307: Cannot find module '@rbxts/compiler-types'"},{"fix":"Use `import { Compiler } from 'rbxtsc'` or `const { Compiler } = require('rbxtsc')`.","cause":"Importing default export as named or using CJS `require` incorrectly.","error":"TypeError: Compiler is not a constructor"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}