Establish a clear rule for configuration values

[dnaka91]

WIP: This issue is not done writing yet, please wait with comments. I just didn't want to lose state of this write up and created the issue already for now.

At the moment we have many different ways of definiting options for Trunk and the various pipelines it supports. So far we don't have a very clear rule about where a configuration option belongs and having a clear rule would give several benefits.

On one side it would make it easier in the code and give allow for easy answers/decisions to requests for new feature flags. On the other side it can help users of Trunk to have an easier understanding about when a configuration is used (in case there are multiple ways of defining the same option).

Ways of defining a configuration

So far we have 4 different ways of defining configuration values:

• In the target HTML file (often just index.html), through various <link> tags which are to Trunk and replaced during compilation.
• In the Trunk.toml configuration file with the TOML format.
• Through environment variables.
• With arguments and flags when invoking the Trunk application in a terminal.

Values defined in the HTML file are most of the time very specific to a single resource. For example several SASS files that each have their own specific configuration for processing. As these are specific to the resource, they are the only way of defining the configuration.

Other settings can mostly be defined through the other defined means and build a hirarchy chain where one location has a higher priority than the other and if the same setting is defined in two or more places, the higher priority overwrites the other(s). The hierarchy is as follows, from low to high: First Trunk.toml, then environment variables and lastly the CLI arguments.

Proxies, hooks and tools are unique to the Trunk.toml and can not be defined or overriden by any other means.

Some other settings have special rules when overiding, like the --release flag activating the release builds, but missing this setting in a higher priority level won't deactivate it again.

Conflicts/unclarity in where to add new configuration

The above described system works well for the current values, but for several open issues and PRs it is sometimes onclear where the setting should be located best. This arises most of the time for settings that can apply to both the cli/env/toml setting and the HTML config.

Existing issues & PRs

Issue #290 asks to add an extra flag that allows to run examples instead of the main application, reusing the same HTML entry point. This allows for quick demonstration and testing of examples and would be a CLI setting only. The question is, what settings should be used, defaults, the ones defined for the main entry point, or even different ones? And where would these be defined in the last case?

PR #295 is an idea of myself to allow passing custom profiles to cargo instead of using the debug or release. It's helpful in a multi-crate repo with workspace, where the profile options can only be defined on a workspace level. This turned out to become tricky for selecting the right configuration. Should wasm-opt be run and SASS be transformed to expanded or compressed CSS? As there are more options than just debug/release and no further detail is known about the profile, it's difficult to decide these options. Therefore, maybe a new approach to define these settings is needed.

There are a few other issues with similar problems but these two are the most recent ones. In addition, on Discord the question often comes up how to switch certain pipeline settings when running in debug or release mode. The current solution is to duplicate the HTML file and changed the wanted options.

Solutions & Ideas

@thedodd and me already discussed this in a direct conversation on Discord and we came up with several ideas, not just decide upon a clear rule for configuraiton values, but to have a better way of defining these options in regards to profiles.

As these changes would break the current setup for all users without an automatic migration path, we should further discuss these solutions and it would be great if current users of Trunk could give their thoughts about it as well.

Removing HTML config in favor of Trunk.toml

Our current idea is to move away from setting configuration values in the HTML entry point and instead allow to define different sets of settings in the Trunk.toml file instead. The HTML file would become more or less of a template, having either a full templating engine run over it or, even simpler, use a HTML comment as marker that is later replaced with the right resource links.

The injected content would be derived from the Trunk.toml based on the selected profile or config set. TOML allows us to have more control over the settings, allowing to define and override defaults for different profiles and still have specific settings for single pipelines in one place.

For example, it could allow to have profile specific settings that align with cargo's profiles:

# Settings in cargo + trunk to produce a WASM app with minimal file size.

# Cargo.toml
[profile.release]
lto = true
opt-level = "z"

# Trunk.toml
[profile.release]
wasm-opt-level = "z"
sass-format = "compressed"

This can then be combined with pipelines defined in Trunk.toml:

# Replacement for the current settings in index.html

[sass.index] # `index` is the unique identifer for this resource
file = "index.sass"

Both combined together would allow to override profile settings for specific resources:

[profile.release]
wasm-opt-level = "z"
sass-format = "compressed"

[sass.index]
file = "index.sass"

# for whatever reason, we want this specific resource to be rendered expanded.
[sass.index.profile.release]
format = "expanded" 

The above can become repetitive and lengthy, but the expectation currently is to not have too many of these overrides for specific resources. In addition, TOML has inline tables for a more compact representation:

[sass.index]
file = "index.sass"
profile = { release = { format = "expanded" } }