Aliases and .luaurc✎

@roact/Component is a require that does not say where Roact is. The path lives in a .luaurc, and the alias is the name you use instead — so a package that moves is one file changed rather than every graph that reads it.

An alias belongs to the project, not to a graph. The file is committed, so everyone working in the repository resolves @roact to the same place, and two graphs cannot disagree about it.

{
	"languageMode": "strict",
	"aliases": {
		"roact": "./Packages/Roact",
		"shared": "./src/Shared"
	}
}

Where the file goes

Anywhere. A .luaurc applies to its own directory and everything under it, so a project can have one at the root and another beside a corner of itself that needs something different.

Where a relative path lands

Against the .luaurc that defined it — not against the file doing the requiring. "If an alias is bound to a relative path, the path will be evaluated relative to the .luaurc file in which the alias was defined."

Naming one

• Case does not matter. @Roact and @roact are one alias. Defining both in one file is defining one alias twice, and Roswaal says so rather than letting you write a file whose behaviour nobody can predict.
• Letters, digits, ., - and _. A name cannot contain / or \ — the separator is what ends the alias and starts the path after it.
• @ on its own is reserved.

An alias that points at another

Allowed, and followed: "This search continues iteratively if a chain of aliases must be resolved." So "ui": "@roact/Component" is Packages/Roact/Component if @roact is ./Packages/Roact, and each link resolves against the file that defined that link rather than the first one.

Editing one

A .luaurc is a file in the project tree, under Graph content beside your graphs — Roswaal reads it rather than writing it, which is the line that section is drawn on. Double-click it to open the alias editor: what this file defines, where each one lands once the chain is followed, and underneath, what it inherits from above.

• Inherited aliases are shown but not editable. They belong to another file, and the way to change one is to open the file that defines it.
• Every write splices the aliases object and leaves the rest of the file exactly as it was: languageMode, lint settings, fields Roswaal has never heard of.
• A file with comments inside its aliases is refused rather than rewritten, and says why. An edit reorders the entries, and a note about why a package is vendored cannot survive that.

What Roswaal checks

The second and third rows are the same specifier and different answers, and the difference is deliberate. A project that uses alias maps and does not name this one has a misspelling. A project with no .luaurc anywhere may be generating one at build time, or keeping it outside the folder Roswaal opened — refusing to compile that would be refusing a project that builds.

Last reviewed 16 September 2026 by @neopolitans

To verify: someone who has shipped a Lune project with a .luaurc should check this against a real alias map — especially a project with more than one file, where inheritance and relative paths stop agreeing with the simple case.