rbx-forge

A roblox-ts and Luau project workflow tool for fully-managed Rojo projects

rbx-forge gives you simple commands (init, watch, build, open) that handle the full workflow: TypeScript compilation → Rojo builds → Studio integration -> sync changes back to the filesystem. No script boilerplate needed.

Requirements

• Node.js >= 22.16.0
• Rojo - Install from rojo.space or optionally via uplift-games/rojo
• Task Runner (optional) - npm, pnpm, or mise for script generation

Installation

The recommended way to use rbx-forge is with npx, which automatically installs it to your project:

npx rbx-forge init

This runs you through a setup wizard that installs rbx-forge to your project, creates rbx-forge.config.ts, and generates task runner scripts.

Alternative: Global Installation

If you prefer to install globally:

pnpm add -g rbx-forge

Then run rbx-forge init in your project.

Quick Start

# Install and set up
npx rbx-forge init

# Start development server
rbx-forge start  # Builds your place file and opens Studio

# When you're done
rbx-forge stop

Commands

| Command | Description | | ---------- | ------------------------------------------------------------- | | init | Initialize a new rbx-forge project | | build | Build the Rojo project to an output file | | compile | Compile TypeScript to Luau (roblox-ts projects only) | | serve | Start the Rojo development server | | watch | Watch and rebuild on file changes | | start | Full workflow: compile, build, open Studio, optional syncback | | stop | Stop running Roblox Studio processes | | open | Open place file in Roblox Studio | | restart | Restart the current workflow | | syncback | Sync changes from place file back to source | | typegen | Generate TypeScript types from Rojo sourcemap |

Configuration

rbx-forge uses rbx-forge.config.ts (recommended), rbx-forge.config.json, or package.json for configuration. The init command creates a TypeScript config for you with full type safety.

Basic config

import { defineConfig } from "rbx-forge";

export default defineConfig({
	// Where Rojo builds to
	buildOutputPath: "game.rbxl",

	// Customize generated script names (optional)
	commandNames: {
		build: "forge:build",
		serve: "forge:serve",
	},

	// "rbxts" or "luau"
	projectType: "rbxts",
});

Advanced options

You can also configure:

• roblox-ts compiler settings (rbxts.args, rbxts.command)
• Syncback behavior (syncback.runOnStart, syncbackInputPath)
• Type generation (typegen.include, typegen.exclude, typegen.maxDepth)

See docs/configuration.md for all options.

Script Generation

rbx-forge init creates scripts in your task runner:

package.json:

{
	"scripts": {
		"forge:build": "rbx-forge build",
		"forge:serve": "rbx-forge serve"
	}
}

mise (.mise.toml):

[tasks."forge:build"]
run = [ "rbx-forge build" ]

Customize these however you want - add pre/post hooks, chain commands, etc.:

{
	"scripts": {
		"forge:build": "echo 'Building...' && rbx-forge build",
		"forge:serve": "rbx-forge build && rbx-forge serve",
		"preforge:serve": "echo 'Preparing to serve...'"
	}
}

rbx-forge respects your runner context when chaining commands, so your hooks will execute.

Or skip scripts entirely and use the CLI: rbx-forge build

License

MIT - Copyright for portions of rbx-forge are held by osyrisrblx 2021, as part of rbxts-build. All other copyright for rbx-forge are held by Christopher Buss, 2025.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

• osyrisrblx - Original author of rbxts-build