Resolve the need for custom arguments

[panstromek]

Description

As a developer, I need to pass custom arguments to build.

I recently converted a mid-size project from webpack to vite and this was a major pain point.

This has been discussed a few times already, but non of the suggested solutions seems particularly good.

Since vite positions itself as a build system that is very customizable and intended to be built upon, it's pretty much expected that big projects will need to parametrize their build. Therefore I'd object to a comment that this is out of scope for Vite.

What's actually needed?

• Some way to pass parameters to vite that changes the behaviour of the build (e.g. --analyze, --release, --target <platform>)
• It's very common to add shortcuts for common sets of parameters to "scripts" in package.json (e.g. yarn build:android
  • These should still allow passing more parameters like yarn build:android --release
• The mechanism has to be portable between platforms

Suggested solution

There are a few ways to go about this, some of them have been proposed before:

• Accept unknown arguments from the CLI and (optionally) pass them through to the build config (or just keep them in argv)

  • This has been rejected with the reason that adding a parameter to vite itself would be a breaking change, which is a reasonable concern

• Follow what npm or cargo does - allow pasting custom parameters after a delimiter (e.g. --)

  • -- specifically doesn't work for package.json shortcuts because it's already used by npm, yarn throws a warning
  • something like --custom-args could work, but it should probably be something shorter
    • note that it has to be just a delimiter, not a parameter with an argument, to support appending more arguments when used with yarn run

• Customize the build with environment variables

  • this has been suggested as a solution in previous issues, but it has a few problems
    • passing them through command line is not portable (works differently on windows/linux)
    • using env files instead means you have to create potentially a power set of all possible combination of parameters
      • similar can be set about multiple custom `vite.config.ts files

• Wrap the CLI in a custom build.js

  • This is what I did in the end:

const validArgs = [
  "--release",
  "--no-checker",
  "--android",
  "--ios"
]
// filter out our arguments from `process.argv` fo avoid vite error and put them into custom environement variable
const BUILD_ARGS = [];
const rest = []
for (const arg of process.argv) {
  if (validArgs.includes(arg)) {
    BUILD_ARGS.push(arg);
  } else {
    rest.push(arg)
  }
}

process.env.BUILD_ARGS = BUILD_ARGS.join(' ');
process.argv = rest;

import('./node_modules/vite/bin/vite.js')

• This solves all the issues, but it feels a bit hacky
  • it's not mentioned in the documentation as a supported pattern
  • relies on the /node_modules/vite/bin/vite.js always being an entry point
  • modifying built in arguments and envirnoment seems problematic
  • custom env variable has to be parsed in vite config file again

A potential solution would be to "bless" the wrapper pattern to make sure it's supported going forward. Notably mention it in the docs with some recommendations and best practices

Probably the nicest form of that would be to export entrypoint function like startCLI(env, args, customArgs), to avoid the need to mess with the process.* variables. Custom arguments could then be passed down to the config.

Alternative

No response

Additional context

This has been discussed in #7065 #1554 and #2891

Validations

• Follow our Code of Conduct
• Read the Contributing Guidelines.
• Read the docs.
• Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

[maxpatiiuk]

Related discussion in vitest-dev/vitest#6593