roblox-ts

library3.0.0jsnpmunverified

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.

devops web-framework

npm install roblox-ts

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ROBLOX-TS

roblox-ts

devopsjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Compiler

✓ import { Compiler } from 'rbxtsc'

✗ const Compiler = require('rbxtsc').Compiler

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

default

✓ import robloxTs from 'rbxtsc'

✗ const robloxTs = require('rbxtsc')

Default export is the Compiler class. Use named import for clarity.

ProjectInfo

✓ import type { ProjectInfo } from 'rbxtsc'

✗ import { ProjectInfo } from 'rbxtsc'

Use type-only import if you only need the type, to avoid code generation.

ProjectInfo

✓ const { ProjectInfo } = require('rbxtsc')

✗ const ProjectInfo = require('rbxtsc').ProjectInfo

Both work, but destructuring is preferred in CJS.

TSConfigReader

✓ import { TSConfigReader } from 'rbxtsc'

✗ import { TSConfigReader } from 'tsconfig-reader'

Part of roblox-ts, not a separate package.

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

rbxtsc --version

Debug

Known issues

breakingv3 removed support for Node 14; requires Node 18+.

fix

Upgrade Node.js to 18 or later.

affects: >=3.0.0

breakingv2.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.

affects: >=2.3.0

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

fix

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

affects: >=3.0.0

gotchaIn `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.

affects: >=2.0.1

gotchaEnum 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.

affects: >=2.3.0

gotchaTypeScript `accessor` keyword is not supported and will produce a diagnostic.

fix

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

affects: >=2.1.0

Errors

Common errors & fixes

Error: Cannot find module 'rbxtsc'

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 TS2307: Cannot find module '@rbxts/compiler-types'

Missing type definitions package for Roblox APIs.

fix

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

TypeError: Compiler is not a constructor

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

fix

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

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

typescriptrequiredRequired for TypeScript language services and compilation pipeline

@rbxts/compiler-typesrequiredProvides type definitions for Roblox APIs

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/roblox-ts/roblox-ts ↗

packagehttps://www.npmjs.com/package/roblox-ts ↗

homepagehttps://roblox-ts.com ↗