Provide Angular build context to external tool configuration files

[dgp1130]

🚀 Feature request

Command (mark with an x)

• build

Description

Spin off from PurgeCSS discussion in #20015.

It would be nice for external tool configuration files (like Tailwind) to have some knowledge about the Angular build context in order to conditionalize their configurations. This could allow ng build --configuration production to change the config used by other tools and affect their builds as well. This allows other tools in a project to be more intelligent about the intent of a build and do what the user expects.

Describe the solution you'd like

There are a couple possible implementations of this.

1. Set an environment variable like NG_BUILD_CONFIGS="foo,bar,baz". Then config files could do something like:

const enableOptimizations = process.env['NG_BUILD_CONFIGS'].split(',').includes('production');

This would decouple the Angular CLI from any specific tools and allow the individual tool configs to define the semantics for each configuration. Similarly, the semantics for each configuration are also defined directly in the tool's config file rather than angular.json. That seems weird to me, but arguably it's a benefit so 🤷‍♂️. It also means that the config needs some knowledge of Angular, which isn't too bad considering its in the config, not the tool library, but this can still be undesirable.

2. Add an env option in angular.json. Each configuration in the angular.json file could include an env map that looks like:

{
  "projects": {
    "my-project": {
      "architect": {
        "build": {
          "options": {
            "env": {
              "MY_BUILD_ENV": "development",
            },
          },
        },
        "configurations": {
          "production": {
            "env": {
              "MY_BUILD_ENV": "production",
            },
          },
        },
      },
    },
  },
}

The Angular CLI would parse and set the relevant environment variables during a build. Then tool configs could look for the project-specific environment variables like so:

const enableOptimizations = process.env['MY_BUILD_ENV'] === 'production';

This would still give users full control over the semantics of any given environment variable and they can choose its value on a per-configuration basis. The challenges here include merging multiple configuration environment variables which might conflict and that this environment would apply to all tools used by the Angular CLI. Users might also break something by setting a variable they probably shouldn't (such as PATH or other system variables) and breaking the CLI.

3. Just have users set the environment variable on the command line:

MY_BUILD_ENV="production" ng build --configuration production

Then use that variable in the tool config just like previously:

const enableOptimizations = process.env['MY_BUILD_ENV'] === 'production';

This requires no effort on the Angular CLI side and users can do this today. The downside here is that it requires special knowledge of how to build a particular app. A new developer would reasonably expect ng build --configuration production to do everything it needs to, and then be surprised something didn't optimize because they didn't set MY_BUILD_ENV="production". Projects could wrap such a command into an npm run build:prod which sets the variable, but not everyone will use it. This is also a cross platform issue, as I don't think there is a Unix and Windows compatible way of doing this (see this question), so supporting both environment for build is more hassle for the user.

There are likely other possible implementations that have their own trade offs. We'll need to discuss this more and come to a decision on how to move forward here.

[ahasall]

Users might also break something by setting a variable they probably shouldn't (such as PATH or other system variables) and breaking the CLI.

We could mitigate this concern by requiring all environment variables to begin with NG_.

[nartc]

https://github.com/tailwindlabs/tailwindcss-jit Just want to bring this to you guys' attention that is Tailwind JIT is in the work. As soon as this is stable, the need for Purging is obsolete. Although, there will be option from the Tailwind side to go back to AOT mode which, again, requires Purge functionality. So I guess this issue is still relevant

[dgp1130]

Had some more discussion on this today. While this build context issue is generic to any executable config file for any tool, the main motivation is for Tailwind. We do have a couple other executable configs (Karma for instance), but these have more direct integration where we pass in specific, known data about the build. So there isn't much need for this particular feature right now outside of Tailwind and we'd like to move away from the executable config format as much as possible due to its security and maintainability implications. For that reason we probably won't add this kind of support unless we have a specific need for it.

JIT mode seems like an easy answer to the Tailwind purging issue, avoids this issue entirely, and seems to be on track in a reasonable time frame. We'll need to do a bit of testing to confirm that Tailwind JIT works well with Angular, and if so, that seems like a better solution than inventing a scheme to pass build context to external config files. We'll keep an eye on Tailwind JIT for now, and hopefully we can use that to avoid this build context issue entirely.

[nartc]

@dgp1130 Thanks for sharing that insight. Can we get some update regarding Tailwind JIT testing as it goes along or as you guys make any decision for TailwindJIT? As of right now, Tailwind JIT needs to be included in postcss.config and that's not very straightforward to have a custom postcss.config to work with Angular, is it?

[angular-robot]

Just a heads up that we kicked off a community voting process for your feature request. There are 20 days until the voting process ends.

Find more details about Angular's feature request process in our documentation.