Lattice UI Docs Docs

Workspace Governance

Monorepo governance rules for package consistency and release flow.

On this page

Audience: monorepo contributors and maintainers.

This page documents contributor workflows for this repository.
For app-level dependency installation and upgrades, use the CLI section: CLI.

Goals

  • Keep package structure modular without increasing maintenance cost.
  • Enforce lockedstep versioning for publishable packages.
  • Prevent dependency and metadata drift with deterministic scripts.

Create a New Package

  1. Run pnpm package:new --name <kebab-name>.
  2. Optionally include deps and app linking: pnpm package:new --name slider --deps core,focus --app-link playground
  3. Implement code in packages/<name>/src.
  4. Verify policy with pnpm workspace:check.

Note: pnpm package:new is a contributor script for this monorepo and is separate from the public lattice create/add/upgrade/doctor CLI workflows.

Dependency Rules

  • Internal workspace dependencies must always use workspace:*.
  • Publishable packages must include peer deps:
    • @rbxts/react: ^17
    • @rbxts/react-roblox: ^17
  • Canonical metadata and typecheck paths are auto-fixed by pnpm workspace:sync.
  • Tooling packages listed in workspace.policy.json.toolingPackages are exempt from Roblox defaults (main, types, rbxtsc scripts, canonical tsconfig.typecheck.json) while remaining in lockedstep versioning and changeset fixed groups.

Changeset Rules

  • Public package changes require a changeset (pnpm changeset:add).
  • apps/* workspaces are ignored from publish versioning.
  • Publishable packages/* are locked in one fixed version group.

Manual Release Steps

  1. Ensure there is at least one pending changeset.
  2. Run pnpm release:prepare.
  3. Review changed package versions and changelog entries.
  4. Publish with pnpm release:publish.
  5. Inspect pnpm-publish-summary.json if needed.

Local Release Checklist (No CI)

Run this sequence from the repository root before a release:

  1. pnpm run verify:workspace
  2. pnpm test
  3. pnpm run test:rbx
  4. pnpm run changeset:status
  5. pnpm run release:prepare
  6. pnpm run release:publish:dry-run
  7. pnpm run publish:summary

Optional/manual RBX execution (not part of the official release chain):

  1. pnpm run test:rbx:headless (requires environment write access to ~/Documents/Roblox/Plugins)
  2. If headless fails with Operation not permitted (os error 1), run pnpm run test:rbx:run and execute in Roblox Studio manually.

Recommended commit split:

  1. Commit test infrastructure and documentation changes first.
  2. Commit release:prepare outputs (version/changelog/lockfile updates) separately.

v1.0.0 Upgrade Plan

  • Stay on lockedstep 0.x until the v1 milestone is ready.
  • Add one coordinated major changeset.
  • Run pnpm release:prepare and publish all packages together.