Improve @vue/babel-preset-app API by using explicit configuration

[ntsim]

What problem does this feature solve?

Currently @vue/babel-preset-app receives a variety of configuration explicitly as options, but also receives a bunch of environment variable based configuration to bootstrap itself. Whilst innocent looking enough, this creates hidden dependencies that can only be ascertained by looking at the source code. This is somewhat at odds with other Babel presets/plugins/etc that usually require more explicit configurations.

The end result is somewhat 'magical' behaviour that can create a confusing user experience in certain scenarios.

Example

In my specific case, I was using one of the Jetbrains editors (Webstorm, etc), where it can run entire subsets of tests directly from the GUI. When using Jest, this is achieved by invoking Jest directly with a specific test pattern. A Babel transpilation step is also no problem as long as the configuration can explicitly be set somewhere i.e. .babelrc or babel.config.js.

Unfortunately, the GUI-based test runner does not work out-of-the-box with @vue/babel-preset-app because of the need for the environment variables to be set.

Workarounds

1. Set the required environment variables directly in the GUI's test runner configuration. This could be confusing to such users and does not lead to a streamlined experience.

2. Set the environment variables explicitly in the babel.config.js. This feels unclean and begs the question why the configuration options are not available directly in @vue/babel-preset-app.

   if (process.env.NODE_ENV === 'test') {
     process.env.VUE_CLI_BABEL_TARGET_NODE = true;
     process.env.VUE_CLI_BABEL_TRANSPILE_MODULES = true;
   }
   
   module.exports = {
     presets: [
       '@vue/app',
     ],
   };

What does the proposed API look like?

The configuration API of @vue/babel-preset-app could be improved by making it more transparent and explicit. More options could be added to either replace the existing environment variables or live alongside them (with less priority given to environment variables).

This could then be used in combination with a more 'typical' Babel configuration where we define different environment configurations:

module.exports = {
  presets: [
    '@vue/app'
  ],
  env: {
    test: {
      presets: [
        ['@vue/app', {
  	  targetNode: true,
  	  transpileModules: true,
  	}],
      ],
    },
  },
};

Note that the options given above do not have to be the same as above, but they are just mapped directly from the current environment variables that are used when running tests i.e. VUE_CLI_BABEL_TRANSPILE_MODULES and VUE_CLI_BABEL_TARGET_NODE.

This should remove any hidden dependencies on environment variables and allows us to have more fine-grained control over how @vue/babel-preset-app bootstraps Babel.

[LinusBorg]

Hi thanks for the detailed suggestions!

We ackowledge that the current preset is doing some "magic" behind the curtains, but there are reasons for this implementation - mainly that we don't want to burden the user with having to maintain dynamic changes to this preset's options in order to make babel behave as required in different modes.

For example, when running jest with vue-cli-service test:unit, we dynamically set the target to node to skip polyfills and transforms for old browsers, and we make it transpile modules to commonjs. Without those changes, jest can't run - which you experienced first-hand.

Now, with the options that you proposed, that problem would still exist. We would have to generate a bable config that looks like this:

odule.exports = {
  presets: [
    '@vue/app'
  ],
  env: {
    test: {
      presets: [
        ['@vue/app', {
  	  targetNode: process.env.NODE_ENV === 'test',
  	  transpileModules: process.env-NODE_ENV === 'test',
  	}],
      ],
    },
  },
};

I'm not sure that we want to expose this.

Furthermore, looking at ``build --modern`, we either have to put some additional env variables into this config to make modern-mode compiles work, or we would have toload this config behind the scenes and change it only whe we complie the modern bundle. Again, magic in the background.

So the question is, which trade-off do we want to acccept?

• expose these dependencies to env variables to the user i order to make i.e. direct runs of jest work better?
• abstract away all of that for the user, which means he has to go through vue-cli-service or do some source digging if he wants to break out of it.

[ntsim]

Hi @LinusBorg, your code snippet suggests that we would need process.env.NODE_ENV === 'test' checks, but this seems like it would be unncessary as Babel automatically picks up the environment from NODE_ENV and merges in the relevant environment block from the configuration. It should appear more like my original code snippet I think.

In regards to modern builds, this is somewhat troublesome as the VUE_CLI_MODERN_BUILD env variable seems to be consistently referenced across the CLI's codebase. Personally, I don't think environment variables with such a wide scope is a good thing, at least from a code hygiene perspective. Changing such variables becomes such a big hassle in the future!

It feels to me like using different NODE_ENVs for targetting different environments (e.g. development-modern, development) would lead to clearer code in this regard. Then we could have additional Babel environment blocks for each, etc.

Anyway, because modern builds are currently intrinsic to Vue CLI, I think the immediately realistic options are to: A) Leave it alone or B) Introduce it into the config directly via it's environment variable:

module.exports = {
  presets: [
    ['@vue/app', {
      modernBuild: process.env.VUE_CLI_MODERN_BUILD,
    }],
  ],
  ...
};

Obviously you have your reservations about the latter as this would introduce some additional configuration complexity to the user. I think this may not be a major problem as it feels like users that want to be 'hands-off' with configuration are unlikely to mess around with their babel.config.js in the first place. The option should still be there for more advanced users to tweak if they feel they need to.

From my perspective, I think it's good to have explicit configuration options (with sensible defaults), than it is to have magic configuration that a user can't properly understand without diving into code. We've all had frustrating experiences where we haven't fully understood how a configuration works. It's probably doubly frustrating when the configuration happens magically!

I think at a minimum it would still be good to at least convert some environment variables to config options (such as the ones mentioned in the original issue). It doesn't seem to me like there would be an overwhelming amount of additional configuration from doing this either.

[yyx990803]

The Jest plugin explicitly states that:

Note that directly running jest will fail because the Babel preset requires hints to make your code work in Node.js, so you must run your tests with vue-cli-service test:unit.

If your IDE can run arbitrary command line commands, then running vue-cli-service test:unit is the proper way to run your unit tests.

The babel preset is designed specifically to be used with Vue CLI, so opening up all the internal options will make the public configuration extremely complex. Other than the Jest example, we haven't seen any real problem to warrant the added complexity in the babel config. Also, even with your suggestion, it's still "magical" since it works only because Jest implicitly sets NODE_ENV to test during tests.