rproj

rproj is a guided Windows CLI for setting up Roblox/Luau development and creating consistent projects.

Status: pre-release alpha. The main workflows work, but the command surface, generated files, and rproj.toml schema may change without migration support. Use it for real projects only when you are willing to review generated changes and update with the tool.

What rproj does

rproj connects two layers that are usually assembled by hand:

1. Machine setup installs and configures development applications, command-line tools, Roblox Studio plugins, and VS Code extensions.
2. Project setup turns your choices into a Roblox project with pinned tools, dependencies, editor settings, quality checks, and optional asset workflows.

It explains the available choices before applying them. It does not hide the underlying ecosystem: generated projects remain ordinary Rojo, Rokit, Wally, Luau, and Git projects that can be maintained without rproj.

Run rproj with no arguments in a terminal to open the workspace hub. It summarizes the current directory, machine setup, saved setups, project template, and version state, then launches the selected existing command after restoring the terminal. Direct commands remain the stable interface for scripts and repeatable workflows.

Ecosystems

Use rproj info to browse the complete current catalog and rproj info <key> to inspect one entry.

Requirements

• Windows with winget
• Rust and Cargo for installation from crates.io or source
• Network access while installing tools and packages

Install

cargo install rproj

The repository version can be installed with:

git clone https://github.com/chatarabdelilah/rproj.git
cd rproj
cargo install --path .

First project

rproj new my-first-game

On a new machine, rproj first offers the missing machine-level tools. It then asks how the project should manage packages, which packages and capabilities it needs, and which generated files to keep. The final summary is reviewable before anything is created and lists the relevant rproj configure commands for the chosen project.

After creation:

cd my-first-game
rproj watch

rproj watch restores missing project dependencies, regenerates the Rojo sourcemap, and starts the development watcher.

Commands

The hub keeps project actions visible when they cannot run, along with the exact missing file or directory. It examines only the current directory: it does not search for or manage a projects-root library. Select New Project to enter a name, Catalog to browse the ecosystem, or another task to leave the hub and run the corresponding command normally. Use arrows and Enter to navigate, Esc to leave, and ? for help.

Generated project

The exact tree follows your choices. A full project can include:

my-first-game/
|-- default.project.json
|-- rokit.toml
|-- wally.toml
|-- selene.toml
|-- stylua.toml
|-- .luaurc
|-- .gitattributes
|-- .gitignore
|-- rproj.toml
|-- src/
|   |-- client/
|   |-- server/
|   `-- shared/
|-- tests/
|-- jest.project.json (Jest Roblox only)
|-- jest.config.json (Jest Roblox only)
|-- .lute/check.luau
|-- .github/workflows/ci.yml
|-- figma/
|-- asphalt.toml or tungsten.toml
`-- .vscode/settings.json

rproj.toml records the current project decisions used by rproj upgrade. During alpha, re-scaffolding is preferred when the schema changes substantially.

Testing

Testing is optional. Wally projects can choose either Jest Roblox or TestEZ; git-submodule and dependency-free projects use TestEZ because Jest Roblox is distributed as Wally development packages. The choice is written explicitly to rproj.toml, and rproj upgrade never migrates one runner to the other.

Run the selected runner through:

rproj test
rproj test -t inventory

TestEZ runs through lute test. Jest Roblox installs the official Jest and JestGlobals packages under [dev-dependencies], keeps them and the test mounts out of production default.project.json, and builds tests through the generated jest.project.json. The default local run uses jest-roblox's hidden studio-cli backend and requires Roblox Studio to be installed, logged in, and accompanied by JestRobloxRunner.rbxm. rproj installs or refreshes that plugin when a Jest project is created; rerun rproj setup if installation was interrupted. Explicit backend and workspace arguments are forwarded to jest-roblox unchanged.

Jest CI uses Open Cloud. Add repository secret ROBLOX_OPEN_CLOUD_API_KEY and repository variables ROBLOX_UNIVERSE_ID and ROBLOX_PLACE_ID. The API key needs universe-places:write, universe.place.luau-execution-session:write, and memory-store.sorted-map:read/memory-store.sorted-map:write; the last pair carries streamed GitHub Actions results. CI fails with the missing names instead of silently skipping tests. Queue scopes are unnecessary for rproj's generated single-session CI. Workspace or parallel sharding modes passed through rproj test [args] additionally require memory-store.queue:add, memory-store.queue:dequeue, and memory-store.queue:discard.

jest.config.json is merge-managed: rproj owns backend, rojoProject, jestPath, and test.projects, while preserving other valid JSON fields for filters, coverage, snapshots, and runner options. jest.project.json is fully generated from the current production project and is refreshed by rproj test, rproj watch, and rproj upgrade.

Project template

Run rproj configure project to customize the default.project.json used by projects created afterward. It opens a built-in, keyboard-driven Explorer; it never launches another editor. Existing projects are never changed.

Use the arrow keys to navigate, Enter to edit, Tab to switch panes, and type in searchable class and property pickers. A adds an instance, F2 renames, D duplicates, M reparents, Delete removes, and Ctrl+Z/Ctrl+Y undo and redo. The Inspector provides typed controls for common Roblox properties and attributes plus common project settings. Ctrl+E opens the complete JSON in rproj's internal text editor for uncommon Rojo values and advanced settings. Press ? in the editor for the full key list.

Ctrl+S checks the JSON, rproj-owned paths, and every reachable plain, Wally, and git-submodule mount combination with Rojo before atomically saving it under the rproj configuration directory. Rojo must resolve from the current project or Rokit's global manifest; rokit add --global rojo installs the global fallback. Validation failures leave the draft open and the last valid saved template untouched. A malformed saved file opens directly in JSON repair mode. Ctrl+R restores the built-in template after confirmation.

The project name, DataModel root, src/shared, src/server, and src/client mounts are visible but locked because rproj owns them. Package, module, server-package, development-package, and test mount names and paths are reserved because those directories depend on each new project's choices. Custom $path entries may target only the always-created source directories; use static instances and properties for other additions. The saved template is <rproj config>/templates/default.project.json.

Behavior and scope

• rproj asks before optional machine-level installation and project generation.
• External command output is summarized; --verbose exposes the underlying commands and captured output.
• Existing user-owned configuration is preserved where a command supports merging. Unreadable configuration is refused rather than replaced.
• The current implementation targets Windows. Cross-platform support is not claimed.
• rproj is a development orchestrator, not a package registry, build system, game framework, or Roblox Studio replacement.

Development

cargo test
cargo clippy --all-targets -- -D warnings
cargo package

The codebase separates CLI dispatch, decision modeling, catalogs, command orchestration, and filesystem/process steps. See Architecture, Development plan, UX redesign, and Release process.

Support

Support continued development through Buy Me a Coffee.

License

MIT © Chatar Abdelilah