Rogen | Tool for Feature-based Architecture | Improve Your Codebase

[Clinkety]

Rogen

Feature-based architecture for Roblox

---

What is Rogen?

Rogen is a command line tool that brings feature-based architecture to Roblox.

A bad folder structure slows development. Typical Roblox projects structure their codebases by environment (server, client, shared) at the root level, and then further group files by technical type (Controllers, Services, Utils) inside those roots. This approach gets messy in large codebases. Working on a single feature forces you to navigate through unrelated systems just to gather the related pieces, causing heavy context switching.

Rogen solves this by letting you keep all code for a specific feature inside a single, self-contained folder. In the background, Rogen routes every file to its target Roblox service automatically based on the folder structure and naming rules. Your repository stays clean and localized, while Roblox Studio receives the scripts in the expected service containers.

---

Key Features

• Auto-Routing: Rogen uses naming rules to send files into correct Roblox service containers. It does this using Folder Names, File Names, and Marker Files.
• Multi-Place Support: You can combine multiple directories into one project. This allows you to seamlessly share core code across places.
• Tags & Filtering: Rogen can filter test files, mock data, and development scripts from production builds.
• Modern Tooling: Rogen integrates directly with Luau, roblox-ts, and Darklua workflows.

---

What Top Developers Are Saying

“It has been a game changer for my team and I”
— Acecateer, Technical Director at Wonder Works Studio

“Spent the last couple days refactoring Lua Learning to use Rogen. I love it”
— Zack (boatbomber) Williams, CEO at Torpedo Software

---

Setup & Documentation

You can install Rogen quickly using Rokit:

rogen = "ldgerrits/rogen@1.4.1"

Or use npm:

npm i @ldgerrits/rogen

For full configuration instructions, head over to the documentation:
rogen-playfully.vercel.app

The docs include everything you need to get up and running, including:

• Step-by-step setup guides for Luau, roblox-ts, and Darklua.
• Guides for configuring Multi-Place projects and Tag filtering.
• A complete .rogen.json Configuration and CLI command reference.
• Advanced routing concepts like invisible folders and file hoisting.

[Clinkety]

I have just released a small patch to fix an issue related to .d.ts files. I also made it easier to configure settings.

[Clinkety]

It is now compatible for both roblox-ts AND luau! Anyone can use this now!

[spookwallyjungle]

works with bootstrapper?

Resumen

Este texto estará oculto

[Clinkety]

Yes, anything works with it!

It automatically updates your ‘default.project.json’ to faciltate this project structure. That’s all there is to it!

[Clinkety]

I just released a small patch. It fixed an issue where the internal pruning was too aggressive after an update I made yesterday. If you had a folder without an index.ts / init.luau, then it may not have always generated all the paths that were actually needed. Now, everything works like it should!

[Clinkety]

The tool now also supports .rbxm and .rbxmx files!

[Clinkety]

Rogen - The ‘More Than Just a New Name’ Update

Yesterday’s discussion on Discord led me to overhaul much of the tool. It also led me to rename the tool to Rogen (an abbreviation of Rojo Generator).

Additions

• Config File Support: You can now create a .rogen.json file that will be automatically detected by Rogen. It has the following structure:

{
    "sourceDir": "src",
    "luau": { 
        "outFile": "default.project.json", 
        "outDir": "src", 
        "wrapper": false 
    },
    "ts": { 
        "outFile": "default.project.json", 
        "outDir": "out", 
        "wrapper": "TS" 
    },
    "darklua": { 
        "outFile": "build.project.json", 
        "outDir": "dist" 
        "wrapper": false
    },
    "project": {
        "name": "roblox-project",
        "globIgnorePaths": [
            "**/package.json",
            "**/tsconfig.json"
        ],
        "tree": {}
    }
}

• Darklua Support: Added darklua as additional mode.
• CLI Optional Arguments:
  • -c, --config : Specify a custom config file path.
  • -m, --mode : Specify the mode to run (luau, ts, or darklua). If omitted, Rogen automatically detects your project type (via tsconfig.json or .darklua.json) and runs the appropriate mode(s).
  • -p, --project : Specify a path to a JSON file that contains a Rojo project. If omitted, Rogen will use the project specified in “project” in the .rogen.json file.
• .rbxm and .rbxmx Support: Rogen will now create paths for these file name extensions.

Removals

• appendSuffix: This optional setting only led to confusion and inconsistent behavior when set to true (default was set to false to begin with). It was just not worth keeping around.

[Clinkety]

Rogen - emitLegacyScripts Rework

This is a big update that hopes to solve all remaining issues. It changes the config files, but, more importantly, also affects the generated paths. When you update to this new version (which is recommended), you may need to update your imports.

Fixes

• emitLegacyScripts: When emitLegacyScript is set to false, client scripts had to be routed to ReplicatedStorage. However, if we merged the shared and client code under one directory, it could cause name collisions. To prevent this and to make the behavior consistent, code will now always be wrapped in a ‘client’, ‘shared’ or ‘server’ folder depending on the context.

Changes (Breaking)

• Roblox Paths: The fix for emitLegacyScripts means that many paths have changed a tiny bit (by having a wrapper folder). This also goes for client containers like ReplicatedFirst which will now have a client folder if you ever route code to that container.
• **New and Replaced CLI Args and .rogen.json: ** These new args also correspond to new names in the config.
  • -c, --config : Specify a custom Rogen config file path.
  • -m, --mode : Specify the mode to run (luau, ts, or darklua). If omitted, Rogen automatically detects your project configuration (via tsconfig.json or .darklua.json) and runs the appropriate target(s).
  • -s, --source : Override the directory containing your raw, uncompiled code.
  • -t, --template : Specify a path to a JSON file that contains your base Rojo blueprint. If omitted, Rogen defaults to the inline object or file mapped in your .rogen.json.
  • -b, --build : Override the directory where your compiled/transpiled code lands.
  • -o, --output : Override the name and destination of the final generated Rojo .project.json file.

Removals

• Wrapper Setting: Since scripts always have a wrapper folder, this became useless.

Documentation | Github

[Clinkety]

Rogen 1.0.1 - Toolchain Manager Release!

Additions

• Rokit, Foreman and Aftman Support: Simply run rokit add ldgerrits/rogen or add this to your rokit.toml (or equivalent):

[tools]
rogen = "ldgerrits/rogen@1.0.1"

• -w, --watch: Rogen now supports a built-in watch mode. There’s no need anymore for the chokidar-cli dependency! All you need to do is run rogen -w.

Improvements

• Roblox-ts Stability: Rogen now employs several strategies in order to work more nicely alongside the roblox-ts compiler.

[Clinkety]

Rogen 1.0.2 - Roblox-ts and Darklua Patch

roblox-ts requires a valid default.project.json path to resolve imports, but it won’t generate the code in out until it successfully resolves those imports. By creating empty files, Rogen tricks Rojo and roblox-ts into seeing a valid environment, allowing roblox-ts to compile and immediately overwrite the empty files with actual code.

Fixes

• Compiler Rojo Data Errors: Resolves the compiler error Could not find Rojo data. There is no $path in your Rojo config that covers out\... which occurred because files were pruned before roblox-ts (and possibly Darklua as well) had a chance to compile them. Instead of deleting missing paths from the Rojo project file, Rogen now creates empty placeholder .luau/.lua scripts in your build directory.

[Clinkety]

Rogen 1.1.0 - Stability

Improvements

• Internal Refactor: Split the original monolithic script into smaller modules.

Additions

• Jest Test Suites: Added test coverage to improve stability of Rogen

Fixes

• Fallback Config: Fix error where json parse returned undefined for the fallback config
• Typo in Build Arg: Changed the “d” to “b” as alternative shorter version of “build” arg

[Clinkety]

Rogen 1.1.1 - QoL Update

Additions

• rogen --init: Generate a default .rogen.json config file when doing rogen --init or rogen --i.
• “keepSuffixes” Property and --k: A boolean flag (defaults to false). When set to true, Rogen will preserve your routing suffixes in the script names instead of stripping them out. You can also use the command rogen --k.
• “aliases” Property: If you want to map specific suffixes or folder to a particular service, use the aliases field in the config. You can configure it like this:

"aliases": {
    "Controller": "ReplicatedStorage",
    "Service": "ServerScriptService"
}

[Clinkety]

Rogen 1.2.0 - Multi-Source Update

Rogen now supports codebases that contain multiple directories, allowing you to merge them into a single Rojo project. This is useful for multi-place games where you want to share a core across different places.

• Clean Merging: If src/core and src/hub both contain a shared folder, Rogen will merge the contents of both into a single ReplicatedStorage.shared folder. No duplicates are created.
• Overrides: The order of your sources matters. If both directories contain a file with the exact same name and routing path, the directory listed last will overwrite the former.

Changes

• source (.rogen.json): The root directory (String) or directories (Array of Strings) where your source code lives (defaults to “src”). Passing an array allows you to merge multiple source folders into a single tree.
• –source, -s (CLI): Override the directory containing your code. Can be passed multiple times (e.g., -s src/core -s src/hub) to merge multiple directories.

[Clinkety]

Rogen 1.2.1 - Quick Patch

Fixes

• –watch, -w (CLI): Solved an issue introduced in the last update where using the --watch command would result in an error.

[Clinkety]

Rogen 1.2.2 - Linux Fix

Fixes

• Linux Build Failed: Replaced fs.watch with chokidar to fix error experienced only on Linux.

Improvements

• Custom Mode Config Errors: Added error messages when missing the "output" or "build" fields.

[Clinkety]

Rogen 1.3.0 - Routing Update

This release introduces a few QoL updates that makes Rogen more flexible and powerful.

Additions

• New Routing Strategy: Marker File: You can now place marker files (e.g., an empty file named .server, .client, .shared, or of a custom alias) inside any directory to explicitly set its target service. Previously, relying purely on folder names (like src/server/) meant those names were consumed and stripped from the final Roblox tree. Now, by using a marker file (like src/AntiCheat/.server), Rogen changes the folder’s destination but preserves your folder’s exact name.
• Add Prefix Routing: In addition to suffix routing, you can now route files with prefixes (e.g. serverData.ts, client-input.luau).

Improvements

• Nested Routing Logic: Rogen now handles routing conflicts in an easier and more understandable way. When multiple routes apply to the same file, Rogen follows a simple principle: the most specific route wins. An explicit rule placed directly on a file will always override a general rule set by its parent folder.

Changes (BREAKING)

• keepRouteNames in .rogen.json: To facilitate prefix routing, keepSuffixes was no longer an accurate name, as routing keywords can now appear at the beginning of the file name as well. Please, update your configuration file to use keepRouteNames instead.

[Clinkety]

Rogen 1.3.1 - TypeScript Migration

This is purely an internal codebase update. Rogen functions exactly the same as before.

Improvements (Internal)

• TypeScript Rewrite: Converted Rogen from JavaScript to TypeScript. It is now fully typed to make future development and contributions easier.

[not_Iog1c]

How do I turn this, into that? Everytime I add a new file, I have to reconnect rojo, so that it gets added into studio.

[Clinkety]

@not_Iog1c

Everytime I add a new file, I have to reconnect rojo

Is Rojo crashing for you? If so, that shouldn’t be happening at all.

When you add a file, Rogen (when watching) will automatically update the default.project.json, and Rojo will sync it to Roblox (when serving). What you are experiencing has never been reported before, so I think it may be going wrong with your specific setup. Is there anything you changed in your .rogen.json file? Could you show me your .rogen.json file?

@not_Iog1c

How do I turn this, into that?

I don’t quite understand why you’d want to “turn this into that”. Rogen generates creates individual paths for each file, so it’s expected behavior. That’s what enables it to be so powerful, so you generally don’t want to stop that.

However, one way that you can just sync an entire folder (this stops any routing inside the folder), is to add an init.luau file at the root of that folder. However, this is more of a limitation on Rojo’s part – I wouldn’t rely on this because there’s an outstanding PR that will fix this in Rojo. When that day comes, this specific behavior will be patched out of Rogen.

The best way, if you just want to sync a folder and not individual files, is to add the folder to the tree in the template field of the .rogen.json. This is how we’re syncing the Wally Packages folder as well.