Where are definition files documented? (.d.lua)

[wezm]

Sorry if I've missed something but I can't find information on definition files for describing userdata. From what I've been able to scrape together from issues and discussions it appears that things like

declare class Cat
  Name: string
  function Meow(): ()
end

can be put in a .d.lua file, but it's unclear what the full syntax of these files is, and how they are loaded/used. Any further information would be most appreciated.

[Gargafield]

You can find the type definition of luau core library here

[aatxe]

They’re used solely by type analysis for understanding the types of APIs provided by the embedding environment, but they’re unfortunately not documented in any proper form. As Gargafield mentioned, you can look at some examples in the repository that contain the full surface area of the syntax, but it’s definitely not documentation. Something we’d like to improve, for sure!

[JohnnyMorganz]

Also, just to expand further on the question "and how they are loaded/used", this is implementation-defined. There is no official specification saying that .d.luau files should be loaded in a particular way. When you hook into the Luau Analysis system, you can call Frontend::loadDefinitionFile to load the contents of these files. For example, luau-lsp accepts a configuration to explicitly provide a path to a definition file (it does not look them up automatically), and then it registers them at https://github.com/JohnnyMorganz/luau-lsp/blob/549085713ca97ac87446dbda6671de6031365e16/src/Workspace.cpp#L498.

The files are used to list global types / variables for the embedding env, and not module-specific types (i.e., not to be confused with the way TypeScript's .d.ts files work)

[wezm]

Thanks for this useful info. By "and how they are loaded/used" I mostly meant how do you get luau-analyze to see/use them as this doesn't seem to be mentioned anywhere.

[JohnnyMorganz]

luau-analyze itself has no support for it currently (#1140)

luau-lsp has a luau-lsp analyze command which is a fork of luau-analyze with definition files support (https://github.com/JohnnyMorganz/luau-lsp?tab=readme-ov-file#standalone). You can use it with luau-lsp analyze --definitions=path/to/types.d.luau

[wezm]

Oh! This is extremely useful information. I'll certainly be making use of luau-lsp analyze in the future, thanks.