Build Configurations and h5.json

h5.json is the configuration file the h5 compiler reads for every build. This page covers where the compiler looks for it, how the per-configuration variants h5.Debug.json and h5.Release.json are merged, and how the active build configuration decides whether the minified or non-minified output is wired into the generated HTML.

For the full list of individual options, see Global Configuration. For everything about the resources section specifically, see Resources.

Where the compiler looks for h5.json

The compiler resolves the config file relative to the project (.csproj) directory. For a given file name it checks two locations, in order:

1. <project>/H5/h5.json — an H5 subfolder next to the project file.
2. <project>/h5.json — the project root.

The first match wins. If no file is found at all, the compiler falls back to its built-in defaults and the build still runs.

h5.json is JSON with // line comments allowed, and property names are matched case-insensitively (outputFormatting and OutputFormatting are equivalent). The canonical form is camelCase.

Per-configuration files

Alongside h5.json you can ship configuration-specific files whose name carries the MSBuild configuration:

• h5.Debug.json
• h5.Release.json
• h5.<AnyConfiguration>.json — any custom configuration name works too (for example h5.Staging.json for a Staging build configuration).

The configuration comes from the build — dotnet build -c Release looks for h5.Release.json, dotnet build -c Debug looks for h5.Debug.json, and so on. These files live in the same two locations as h5.json (the H5/ subfolder is checked before the project root).

How the files are merged

When a build configuration is active, the compiler loads h5.json as the base and merges the matching h5.<Configuration>.json on top of it. Values in the configuration-specific file override the base.

The rules in detail:

• If h5.<Configuration>.json exists, it is merged over h5.json. Keys present in both take their value from the configuration-specific file.
• If h5.<Configuration>.json does not exist, only h5.json is used — no merge happens.
• If no configuration is passed to the build, the compiler tries h5.json first, then h5.Debug.json, then h5.Release.json, using the first it finds (no merge in this path).

What to put where

Keep everything shared in h5.json, and put only the values that genuinely differ per configuration in the override file. A common split is to enable source maps and skip minification for local debugging:

{
"output": "$(OutDir)h5/",
"outputFormatting": "Both",
"sourceMap": {
"enabled": false
}
}

{
// Merged over h5.json for `dotnet build -c Debug`.
// Turn on source maps so C# can be debugged in the browser.
"sourceMap": {
"enabled": true
}
}

How the configuration affects the output

The outputFormatting option controls which flavours of the JavaScript are produced:

When Both versions exist, the active build configuration decides which one is referenced from the generated index.html:

• Release — only the minified files are wired up; the minified page is written out as index.html.
• Debug — only the non-minified files are wired up in index.html.
• No configuration — both index.html (non-minified) and index.min.html (minified) are written.

This same configuration-driven selection applies to resources pulled from referenced libraries: a library compiled with outputFormatting: "Both" embeds both the .js and .min.js versions of its assets, and a consuming project picks up the .min.js versions in Release and the non-.min.js versions in Debug. This is why libraries that ship a resources section typically include both a name.js and a name.min.js entry — see the Resources page for the details and a worked example.