Luau Best Practices

Luau engineering

• Use --!strict when it matches the repository. Preserve its established typing level.
• Model domain state with exported types, tagged variants, constrained tables, and narrow function contracts. Avoid any unless an external boundary forces it and narrow immediately.
• Keep modules cohesive. Separate authoritative services, shared definitions, client controllers, and pure domain logic. Avoid circular requires and hidden singleton state.
• Validate external values at remotes, DataStores, attributes, configuration, and deserialization boundaries. Internal functions may trust already-validated types.
• Make lifecycle ownership visible. Disconnect signals, cancel tasks, destroy temporary Instances, and clear player or character state at the owning boundary.
• Prefer tables and data-driven dispatch when they remove repeated conditionals. Do not build a framework for one call site.
• Avoid yielding inside locks, event handlers, or state mutations unless the contract accounts for reentry and stale state.
• Keep comments for non-obvious reasons and invariants. Let names and types explain mechanics.
• Match repository formatting and naming. Use Roblox APIs and existing utilities before adding substitutes.

Verification follows the repository. rojo build checks mapping and serialization, not type correctness or runtime behavior.