lattice-ui Stable direction
import lattice The lattice CLI is a Node tool for Lattice UI projects. It scaffolds new rbxts/react games, installs primitive packages together with their required peers and providers, and audits an existing project for missing dependencies. It is published to npm as lattice-ui and exposes two equivalent binaries: lattice and lattice-ui.
Use the CLI when you want package selection, peer resolution, and project health checks handled for you instead of editing package.json by hand.
Running the CLI
The CLI requires Node 20+. Run it on demand with npx — no install needed:
npx lattice-ui <command> [options]Or install it globally to get the shorter lattice binary:
pnpm add lattice-uinpm i -g lattice-uilattice <command> [options]Both binaries (lattice and lattice-ui) run the same program. Run lattice help for the built-in usage summary or lattice version to print the installed version.
--help / -h prints usage and --version / -v prints the version. As the first argument they short-circuit any command. An unknown global option (any other leading - token) is a usage error.
Commands
| Command | Purpose |
|---|---|
create | Scaffold a new project from the rbxts template. |
init | Add Lattice to an existing project. |
add | Install component packages plus their peers and required providers. |
remove | Remove selected component packages. |
upgrade | Upgrade installed @lattice-ui/* packages. |
doctor | Audit lockfiles, peers, and provider expectations. |
help / version | Print usage or the CLI version. |
create
Scaffolds a new project into an optional [project-path] (defaults to the current directory) from the rbxts template.
npx lattice-ui create my-game --pm npm --git --no-lint| Prop | Type | Description |
|---|---|---|
| [project-path] | positional | Target directory for the new project. At most one is accepted; defaults to the current directory. |
| --yes | flag | Accept defaults and skip interactive prompts. |
| --pm | <pnpm | npm | yarn> | Force a package manager instead of auto-detecting one. |
| --git | flag | Initialize a git repository in the new project. |
| --template | <rbxts> | Project template to scaffold from. Currently rbxts. |
| --lint | flag | Include the lint setup. Conflicts with --no-lint. |
| --no-lint | flag | Skip the lint setup. Conflicts with --lint. |
init
Initializes Lattice inside an existing project. Unlike create, it accepts no positional path and no --git/--no-lint flags, and it supports --dry-run.
npx lattice-ui init --dry-run| Prop | Type | Description |
|---|---|---|
| --yes | flag | Accept defaults and skip prompts. |
| --dry-run | flag | Show what would change without writing files. |
| --pm | <pnpm | npm | yarn> | Force a package manager instead of auto-detecting one. |
| --template | <rbxts> | Template to initialize from. |
| --lint | flag | Include the lint setup. |
add
Installs one or more component packages along with everything they need. Pass component names directly (comma- or space-separated) and/or --preset groups. With no names or presets and without --yes, add prompts you to pick presets and components interactively.
npx lattice-ui add dialog,toast --preset overlayFor each selected component the CLI gathers its npm package, its peers (@rbxts/react, @rbxts/react-roblox), and any required providers, then installs the set minus whatever is already present. Optional providers are reported as suggestions but not installed. After a real run it points you at doctor.
| Prop | Type | Description |
|---|---|---|
| [name...] | positional | Component names to add. Comma-separated lists are split (e.g. dialog,toast). |
| --preset | <preset...> | Add every component in a preset. Repeatable and comma-separated. |
| --pm | <pnpm | npm | yarn> | Force a package manager instead of auto-detecting one. |
| --yes | flag | Skip the install confirmation prompt. |
| --dry-run | flag | Print the planned install command without changing anything. |
remove
Removes the selected component packages. Accepts the same selection inputs and flags as add.
npx lattice-ui remove dialog --dry-run| Prop | Type | Description |
|---|---|---|
| [name...] | positional | Component names to remove (comma- or space-separated). |
| --preset | <preset...> | Remove every component in a preset. |
| --pm | <pnpm | npm | yarn> | Force a package manager. |
| --yes | flag | Skip the confirmation prompt. |
| --dry-run | flag | Preview the changes without applying them. |
upgrade
Upgrades installed @lattice-ui/* packages. Same selection inputs and flags as add and remove.
npx lattice-ui upgrade --dry-run| Prop | Type | Description |
|---|---|---|
| [name...] | positional | Specific packages to upgrade. Omit to consider all installed @lattice-ui packages. |
| --preset | <preset...> | Upgrade every component in a preset. |
| --pm | <pnpm | npm | yarn> | Force a package manager. |
| --yes | flag | Skip the confirmation prompt. |
| --dry-run | flag | Preview the upgrade without applying it. |
doctor
Audits the project and reports issues without changing anything. It checks for a missing or duplicated lockfile, a packageManager field that disagrees with the resolved manager, whether any @lattice-ui component packages are installed, unknown @lattice-ui packages, and missing peers or providers. Missing required providers are errors (non-zero exit); everything else is a warning. It finishes with recommended commands.
npx lattice-ui doctor| Prop | Type | Description |
|---|---|---|
| --pm | <pnpm | npm | yarn> | Force the package manager used for the audit instead of auto-detecting. |
Presets
Presets are named bundles of components so you can install a related set in one go with --preset.
| Preset | Components |
|---|---|
overlay | popover, tooltip, dialog, toast |
form | checkbox, radio-group, switch, text-field, textarea |
Package manager resolution
When --pm is omitted, the CLI resolves a package manager automatically from the project lockfile or installed managers, and pass --pm <pnpm|npm|yarn> to override that choice. doctor surfaces resolution problems: a missing lockfile, multiple lockfiles, or a packageManager field that does not match the resolved manager.
Every component declares the peers it needs (@rbxts/react, @rbxts/react-roblox) and, for layered primitives, optional providers such as @lattice-ui/layer’s PortalProvider. add installs peers and required providers automatically but only suggests optional providers — wire those up yourself when you want the behavior they enable (for example, portal-mounted dialog or menu content).
Dry runs
init, add, remove, and upgrade all accept --dry-run. A dry run prints the exact package-manager command it would run and reports that no files were changed, which is the safest way to preview a change before committing to it.