Rotree watches your source and generates default.project.json for Rojo. You organize code by feature (modules/player/) and name files by role (player.service.ts); Rotree routes each file into the right Roblox service — with no client/server/shared folders to maintain. Works with both Luau and roblox-ts.

Installation

The CLI command is rotree on either channel.

Rokit — recommended for Luau projects:

[tools]
rotree = "notmatical/[email protected]"

npm — recommended for roblox-ts (or anyone with Node/Bun). Add it as a dev dependency, or run it directly:

bun add -d @matical/rotree     # or: npm install -D @matical/rotree
bunx @matical/rotree --watch   # or: npx @matical/rotree --watch

Quick start

rotree --init      # writes a .rotree.json
rotree --watch     # regenerate default.project.json on every change

For roblox-ts, run Rotree next to the compiler (via concurrently):

"scripts": {
	"dev": "concurrently \"rotree -w\" \"rbxtsc -w\" \"rojo serve\""
}

The convention: name by role, realm follows

You never create client/server/shared folders. Instead you name a file for what it is, and its realm falls out automatically:

| You write | Because it's a… | Lands in | | --- | --- | --- | | player.service.ts | service | server (ServerScriptService) | | input.controller.ts | controller | client (StarterPlayerScripts) | | hud.tsx / button.component.tsx | UI | client | | player.ts, dmg.const.ts, net.remote.ts | anything else | shared (ReplicatedStorage) |

Two rules to remember: service → server, controller/component/.tsx → client, everything else → shared.

Two explicit escapes you touch rarely:

• Entry points that run → main.server.ts / main.client.ts (these become Script / LocalScript).
• A whole folder at once → drop an empty .server / .client / .shared marker file in it (great for ui/ or vendored libraries).

Organize by feature, and Rotree mirrors it into the tree:

src/
  main.server.ts               →  ServerScriptService/main
  main.client.ts               →  StarterPlayerScripts/main
  modules/player/
    player.service.ts          →  ServerScriptService/modules/player/player.service
    player-data.ts             →  ReplicatedStorage/modules/player/player-data
  ui/
    .client                       (marker: everything under ui/ is client)
    app.tsx                    →  StarterPlayerScripts/ui/app
  vendor/
    .server                       (marker: server-only library)
    profile-store.luau         →  ServerScriptService/vendor/profile-store

Why not .server.ts for a service? In roblox-ts, .server.ts/.client.ts compile to a Script/LocalScript (an entry point that runs) — you can't import from them. Role suffixes like .service keep the file a ModuleScript, so it routes to the server and stays importable. Use .server/.client only for the handful of entry points that bootstrap the game.

Precedence (most specific wins): file affix → marker file → folder name → .tsx default → shared.

Configuration (.rotree.json)

rotree --init generates a starting config. Everything is optional — the convention works out of the box.

{
	"source": ["src"],
	"jsx": "client",
	"ts": { "output": "default.project.json", "build": "out" },
	"luau": { "output": "default.project.json", "build": "src" },
	"aliases": {
		"repository": "ServerScriptService"
	},
	"template": {
		"name": "my-game",
		"tree": { "$className": "DataModel" }
	}
}

| Field | Description | | --- | --- | | source | Source directory, or an array of them to merge multiple places into one tree. Defaults to ["src"]. | | jsx | Realm that unrouted .tsx/.jsx files default to. Defaults to "client". | | ts / luau / darklua | Mode overrides — where compiled code lands (build) and the generated file name (output). Auto-detected from tsconfig.json / .darklua.json. | | aliases | Register your own role suffixes → services (e.g. "repository": "ServerScriptService"). service, controller, and component are built in. | | template | Base Rojo tree merged with Rotree's generated paths — services with properties, rbxts_include, package folders, etc. Can also be a path to a JSON file. | | keepRouteNames | Keep structural realm keywords in node names instead of stripping them (main.server → main). Defaults to false. |

CLI

| Flag | Description | | --- | --- | | -w, --watch | Regenerate on file changes | | -i, --init | Write a default .rotree.json | | -m, --mode <mode> | luau | ts | darklua | custom (auto-detected if omitted) | | -s, --source <path> | Override source dir (repeatable to merge) | | -o, --output <path> | Override the generated project file | | -b, --build <path> | Override where compiled code lands | | -t, --template <path> | Path to a base Rojo tree JSON | | -j, --jsx <realm> | Realm for .tsx/.jsx (default client) | | -k, --keepRouteNames | Don't strip realm keywords from names | | -c, --config <path> | Custom config file path |

Credits

Rotree is a fork of rogen by LDGerrits, used under the MIT license. Thanks to the original author for the feature-based routing foundation.

License

MIT © notmatical, with original portions © Loek Gerrits.