9. Manifest (wowlua.json)

Every package has a wowlua.json at its root. It is strict JSON (RFC 8259, no comments, no trailing commas). The compiler publishes a JSON Schema, and the manifest should reference it through $schema so editors offer completion and validation:

{ "$schema": "https://raw.githubusercontent.com/DomenikIrrgang/wowlua/main/schema/wowlua-0.1.json" }

wowlua add, remove and update edit the file in place, preserving key order and indentation. Unknown keys are error E4002, so typos are caught. Keys are kebab-case. Schema versions and migration are covered in §9.16.

9.1 Complete example

{  "$schema": "https://raw.githubusercontent.com/DomenikIrrgang/wowlua/main/schema/wowlua-0.1.json",  "package": {    "name": "my-addon",    "version": "1.4.2",    "kind": "addon",    "description": "Tracks things.",    "authors": ["Jane Doe <jane@example.com>"],    "license": "MIT",    "repository": "https://github.com/jane/my-addon",    "wowlua": "^0.1"  },  "addon": {    "name": "MyAddon",    "title": "|cff33ff99My|r Addon",    "title-localized": { "deDE": "Mein Addon" },    "notes": "Tracks things.",    "category": "Combat",    "icon-texture": "Interface\\Icons\\INV_Misc_QuestionMark",    "saved-variables": ["MyAddonDB"],    "saved-variables-per-character": ["MyAddonCharDB"],    "toc-extra": { "X-Discord": "https://discord.gg/example" },    "meta": { "discord": "https://discord.gg/example" }  },  "flavors": {    "standard": {},    "mists": {},    "vanilla": { "interface": [11509] }  },  "dependencies": {    "libstub": { "git": "https://github.com/example/LibStub", "tag": "1.0.3", "kind": "lua-library", "curseforge-slug": "libstub" },    "wowlua-ui": { "version": "^0.4", "optional": true }  },  "addon-dependencies": {    "optional": [{ "name": "Details", "curseforge-slug": "details" }]  },  "features": {    "default": ["minimap"],    "minimap": [],    "experimental-ui": ["dep:wowlua-ui"]  },  "build": {    "src": "src",    "assets": ["media/**"],    "exclude": ["src/**/*.scratch.wowlua"]  },  "check": {    "mode": "basic"  },  "config": {    "logChannel": "SYSTEM",    "maxHistory": 50  },  "profiles": {    "dev": { "config": { "maxHistory": 500 } }  },  "publish": {    "changelog": "CHANGELOG.md",    "targets": {      "curseforge": { "type": "curseforge", "project-id": 123456 },      "wago": { "type": "wago", "project-id": "a1b2c3d4" },      "wowinterface": { "type": "wowinterface", "project-id": 5678 },      "github": { "type": "github", "repository": "jane/my-addon" }    }  }}

Top-level keys: $schema, package, addon, lua-library, types, flavors, dependencies, dev-dependencies, addon-dependencies, features, build, check, config, profiles, minify-levels, publish, meta, fmt, compat, workspace, stdlib.

9.2 package

The addon section is only valid for kind: "addon" (E4317). Library-kind packages may use these sections instead:

9.3 addon

Only for kind: "addon". Every key maps to a TOC directive and/or wowlua:meta.

The TOC ## Version: is always build.version (§9.9.2) and is not configurable. The Addon Compartment entry is registered at runtime by wowlua:launcher and needs no manifest key and no TOC directive.

9.3.1 Per-flavor metadata

addon.flavor-overrides maps a flavor to the metadata fields that differ for it (decision T50). A field that is absent keeps the base value. null removes the field for that flavor.

"addon": {  "title": "|cff1784d1ElvUI|r",  "icon-texture": "Interface\\AddOns\\ElvUI\\Media\\LogoAddon",  "group": "ElvUI",  "flavor-overrides": {    "mists": { "title": "|cff1784d1ElvUI|r Mists" },    "wrath": { "title": "|cff1784d1ElvUI|r Wrath", "icon-texture": null, "group": null },    "standard": { "toc-extra": { "AddonCompartmentFunc": "ElvUI_AddonCompartmentFunc" } }  }}

• Overridable fields: title, title-localized, notes, notes-localized, author, category, category-localized, group, icon-texture, icon-atlas, toc-extra, saved-variables and saved-variables-per-character (decision T128). Localized maps and toc-extra override per key. Load behavior cannot vary per flavor.
• Publish targets restricted with flavors give those flavors' TOCs their site ID (X-Curse-Project-ID, X-Wago-ID, X-WoWI-ID); a flavor no target serves gets none (decision T129).
• Keys must be flavors listed in flavors (E4002 otherwise).
• In the TOC, flavors that share a value share one directive. A value used by only some flavors gets an inline [AllowLoadGameType …] condition in the single layout. That needs inline directives on ## lines (12.0.7+ clients), so toc-layout: "auto" falls back to per-flavor TOCs when a targeted client lacks them (Code generation §14.9).
• wowlua init writes overrides automatically when the adopted addon's TOCs differ per flavor: the value most flavors use becomes the base.

9.3.2 TOC data files

Some addons use the TOC as a data store: QuestieDB, for example, carries about 100,000 X- directives per flavor, read at runtime with C_AddOns.GetAddOnMetadata. Such data does not belong in the manifest. addon.toc-data maps a flavor to files whose lines are appended verbatim to that flavor's TOC (decision T54):

"addon": {  "toc-data": {    "standard": ["tocdata/standard.tocdata"],    "mists": ["tocdata/mists.tocdata"]  }}

• Paths are relative to the package root. The files are build inputs, not assets, and are not copied to the output.
• Each non-empty line must be a ## Key: Value directive. Lines starting with a single # are comments and are skipped. Any other line is error E4002.
• A key the compiler generates itself (Interface, Title, Title-<locale>, Notes, Version, SavedVariables, Dependencies, the publish IDs, …) is error E4002. Only Title-, Notes- and Category- have localized forms, so a key such as IconTexture-blank is ordinary data.
• Keys must be flavors listed in flavors (E4002 otherwise).
• Lines that are identical across flavors are emitted once in a single TOC and get an inline [AllowLoadGameType …] condition otherwise, like flavor-overrides (§9.3.1).
• wowlua init writes tocdata/<flavor>.tocdata when a TOC has more than 200 X- directives (the publish IDs excluded). Flavors whose data is identical share one file.

9.4 flavors

The flavors the package supports: an object whose keys are flavor IDs or aliases (§9.4.1), normalized to IDs.

When flavors is absent, an addon targets standard only, and library, lua-library and types packages support all flavors.

9.4.1 Flavor table

Flavor IDs are Blizzard's game types, as used by TOC load directives. They name the ruleset, not the client. The table is data shipped with the compiler (crate wowlua-flavors). wowlua types sync updates it, and the version in use is pinned in wowlua.lock (Package manager §10.6), so every machine builds identical TOCs. The values below are as of 2026-10-11.

Aliases. Aliases that name a ruleset (retail, mainline, classic-era) are permanent. Aliases that name a client (forever, titan, anniversary) resolve to the ruleset that client runs in the pinned flavor table. When wowlua types sync moves such an alias to another ruleset (for example when Anniversary realms progress), it reports warning W4313 and the manifest keeps working with the new meaning only after the lockfile update is accepted.

The table also records, for each client: supported TOC features (comma-separated interfaces, inline load directives on file and directive lines, [AllowLoadTextLocale], file variables, recognized game-type names and suffixes), the deferred/immediate API markers used by load-order analysis (Compiler §13.6.1), and the site-specific identifiers used when publishing (Publishing §11.3). A flavor without a types package or pinned interface is error E4318.

Closed clients such as Cataclysm Classic 4.4.2 and Wrath Classic 3.4.5 have no client folders. They stay in the table so the TOC features of their last build are known to auto layout decisions. Both support every TOC feature listed above, including file variables, and recognize the game types of their own expansion and all older ones (decision T56). The evidence is that BigWigs and DBM ship single TOCs with these features for them.

9.5 Dependencies

dependencies and dev-dependencies are maps from name to a requirement string or a source object. See Package manager §10.3 for sources and their fields. Additional fields on every dependency:

The standard library (including wowlua:mock for tests) ships with the compiler and is never declared as a dependency.

addon-dependencies:

Entries with flavors are emitted only for those flavors: in a single TOC with an inline [AllowLoadGameType …] directive, otherwise only in those flavors' TOCs.

9.6 Features

"features": {  "default": ["minimap"],  "minimap": [],  "comms": ["dep:libdeflate"],  "full": ["minimap", "comms"]}

• Each feature maps to a list of entries: another feature's name, or dep:<name>, which enables the optional dependency <name>.
• default lists the features enabled unless --no-default-features is given. --features a,b enables more.
• An entry naming an unknown feature, an unknown dependency, or a non-optional dependency is error E4314.
• Features appear in wowlua:meta as features.<name>: boolean, folded at compile time, and can be used in @if and static conditions.
• Feature names are kebab-case in the manifest and camelCase in code (experimental-ui → features.experimentalUi).
• Dependency resolution always covers the union of all features (Package manager §10.4), so enabling features never changes the lockfile.

9.7 build

9.7.1 File variables

WoW clients substitute variables in TOC file lines: [Game] becomes the game type's name (Standard, Mists, Vanilla, …), [Family] becomes Mainline or Classic, and [TextLocale] becomes the client locale. BigWigs, for example, loads Locales\[TextLocale].lua. build.variable-files keeps such lines (decision T55):

"build": {  "variable-files": [    { "path": "src/Init_[Game].lua" },    { "path": "src/Locales/[TextLocale].lua", "locales": ["deDE", "frFR"] },    { "path": "src/Classic_[Family].lua", "flavors": ["mists", "vanilla"] }  ]}

• Every expansion for a targeted flavor and listed locale must exist after the build (E5002). Expansions are compiled or copied like other source files.
• If every targeted client supports file variables, the line is emitted verbatim, in its build.load-order position. Otherwise it is expanded into one line per flavor and locale, each with the matching inline directive or in the matching per-flavor TOC.
• wowlua init writes this list from TOC lines that contain variables or an [AllowLoadTextLocale …] condition.

9.7.2 Files shared between addons

Some load-on-demand addons load files stored in their main addon's folder: TellMeWhen_Options lists ..\TellMeWhen\Options\*.lua, and MythicDungeonTools_UI loads most of MythicDungeonTools' code that way. Two keys express this (decision T58):

// MythicDungeonTools_UI"build": {  "external-files": [    { "path": "../MythicDungeonTools/src/libs/load_libs.xml" },    { "path": "../MythicDungeonTools/src/Midnight/load_midnight.xml", "flavors": ["standard"] }  ],  "load-order": ["../MythicDungeonTools/src/libs/load_libs.xml", "src/Bootstrap.lua"]}// MythicDungeonTools"build": { "shared-files": ["src/libs/load_libs.xml", "src/MythicDungeonTools.lua"] }

• external-files (on the loading addon): TOC lines naming a file of another AddOn by its path in that AddOn's output, relative to this AddOn's folder: ../<AddOn>/<path> (E4002 otherwise). They are emitted verbatim at their build.load-order position, restricted to flavors if given. The build does not check that the file exists, because the other AddOn ships it.
• shared-files (on the owning addon): source files that are built and shipped although this AddOn's TOC does not list them. Files they include through XML are shipped as well. A path that is not a source file of the package is error E5002.
• The files belong to the owner, so they are compiled and checked with the owner's sources. They are never bundled into the owner's own output files, because another TOC loads them. A file both addons load exists once.
• wowlua init writes both keys: the owner's init finds the files its siblings' TOCs (or already adopted siblings' external-files) reference, moves them into its sources with their XML includes, and lists those it does not load itself in shared-files. The loader's init writes the files' new output paths (../<AddOn>/src/…). Either addon may be adopted first.

9.8 check

9.9 profiles

Built-in profiles: dev, release, test. Settings given here are merged over the built-in defaults. A custom profile must name the profile it builds on with inherits (E4315 if missing).

"profiles": {  "release": { "minify": "compact" },  "beta": { "inherits": "release", "log-level": "info", "config": { "maxHistory": 100 } }}

Merging. The effective profile is built from the built-in defaults, then each profile in the inherits chain (base first), then the profile itself, then publish-target overrides. Objects are merged deeply, arrays and scalars replace.

9.9.1 config

The top-level config object defines every user configuration key with its default value. Profiles override values in their own config. The result is exposed as config in wowlua:meta, with a generated type taken from the top-level object. A profile config key missing from the top-level object, or with an incompatible type, is error E4012.

9.9.2 Build version

build.version (in wowlua:meta and the TOC's ## Version:) is derived from package.version:

Without version control, <short hash> is omitted (X.Y.Z-dev).

A converted packager project (compat.packager-keywords) is versioned by its tags like the BigWigs packager: on a tag, build.version is the tag as it is (the packager's @project-version@) and E4319 does not apply (decision T158).

9.10 minify-levels

User-defined minification levels: { name: { extends?: level, passes: pass[] } }. See Optimization §15.4. Unknown pass names are E6003.

9.11 publish

Semantics in Publishing.

Target objects:

9.12 meta

9.13 fmt

See Tooling §16.3.

9.14 compat

9.15 workspace

Only in a workspace root manifest, which may omit package:

Within a workspace, a dependency whose name matches a member library resolves to that member automatically, without a path entry.

9.16 Schema versions and migration

• The $schema URL names the manifest schema version (wowlua-<major>.<minor>.json). Schema files live in the repository's schema/ directory and are referenced through their GitHub raw URL (decision T46). Editors use it. The compiler does not need it.
• package.wowlua (the required compiler version) is read first, before any other validation. If the running compiler does not satisfy it, the build stops with E4300, which names both versions, instead of reporting unknown keys of a newer schema as E4002.
• When the schema changes incompatibly, the compiler accepts the previous major schema with warnings for one release cycle, and wowlua fix --manifest rewrites the manifest in place (keeping formatting) to the current schema.
• wowlua.lock has its own version field. The compiler reads lockfiles of older versions and rewrites them in the current format on the next resolve. A lockfile from a newer compiler is error E4320.

9.17 stdlib

Settings for standard-library modules. Each key is only read when the module is used.

"stdlib": { "log": { "history-size": 1000 } }

9.18 test

Since M9 S4 (blizzard-ui, profile) and S5 (coverage, reporters).