roblox-ts

3.0.0 verified Fri May 01 auth: no javascript

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.

Common errors

error Error: Cannot find module 'rbxtsc' ↓

cause Package not installed or wrong import path (some users try 'roblox-ts' instead of 'rbxtsc').

fix

Install with npm install -D rbxtsc and import from 'rbxtsc'.

error error TS2307: Cannot find module '@rbxts/compiler-types' ↓

cause Missing type definitions package for Roblox APIs.

fix

Install with npm install -D @rbxts/compiler-types and add to tsconfig.json types.

error TypeError: Compiler is not a constructor ↓

cause Importing default export as named or using CJS `require` incorrectly.

fix

Use import { Compiler } from 'rbxtsc' or const { Compiler } = require('rbxtsc').

Warnings

breaking v3 removed support for Node 14; requires Node 18+. ↓

fix Upgrade Node.js to 18 or later.

breaking v2.3.0 removed `rbxtsc init` command in favor of `npm create roblox-ts`. ↓

fix Use `npx create-roblox-ts` or `npm create roblox-ts` to scaffold projects.

deprecated Using `--optimizedLoops` flag is now enabled by default in v3; explicit flag is deprecated. ↓

fix Remove the flag or set `--optimizedLoops=false` to disable.

gotcha In `default.project.json`, node_modules scopes must be explicitly listed (since v2.0.1). ↓

fix Wrap `@rbxts` scope in a folder and list other scopes as needed.

gotcha Enum inverse mapping for string values removed in v2.3.0; string enums no longer support reverse lookup. ↓

fix Use a custom map or `@rbxts/string-enum-utils` for reverse mapping.

gotcha TypeScript `accessor` keyword is not supported and will produce a diagnostic. ↓

fix Use getters/setters with explicit `get` and `set` syntax.

Install

npm install roblox-ts

yarn add roblox-ts

pnpm add roblox-ts

Imports

Compiler

wrong

const Compiler = require('rbxtsc').Compiler

correct

import { Compiler } from 'rbxtsc'

ESM-only since v2. Import from 'rbxtsc' (not 'roblox-ts').

default
wrong
```
const robloxTs = require('rbxtsc')
```
correct
```
import robloxTs from 'rbxtsc'
```
Default export is the Compiler class. Use named import for clarity.
ProjectInfo
wrong
```
import { ProjectInfo } from 'rbxtsc'
```
correct
```
import type { ProjectInfo } from 'rbxtsc'
```
Use type-only import if you only need the type, to avoid code generation.

ProjectInfo

wrong

const ProjectInfo = require('rbxtsc').ProjectInfo

correct

const { ProjectInfo } = require('rbxtsc')

Both work, but destructuring is preferred in CJS.

TSConfigReader

wrong

import { TSConfigReader } from 'tsconfig-reader'

correct

import { TSConfigReader } from 'rbxtsc'

Part of roblox-ts, not a separate package.

Quickstart

Shows how to programmatically invoke the compiler with configuration options.

import { Compiler } from 'rbxtsc';

const compiler = new Compiler({
  project: 'tsconfig.json',
  rojoConfig: 'default.project.json',
  optimizedLoops: true,
  writeTransformedFiles: true,
  plugins: [],
});

compiler.compile().then((result) => {
  if (result.success) {
    console.log('Compilation succeeded!');
  } else {
    console.error('Compilation failed:', result.errors);
  }
});