Environments build API

[dario-piotrowicz]

Hello, I’m opening this discussion to propose a new build API for the environment API (for a prior discussion on this topic see: #16358 (comment))

The Problem

The problem in a nutshell is that the current environments build API based on the buildApp config is too limited, since it only allows a single plugin to control the build process of the whole application, including all of its environments.

This is limiting/problematic for a few reasons:

• Only a single plugin controls the build, this doesn’t allow applications to contain environments that don’t interact with the plugin’s target
• If plugins want to perform some build-time logic without owning buildApp they need to rely on rollup’s writeBundle which can be sub-optimal (since it’s not environment specific/aware)
• It’s not possible for any plugin to run some logic (e.g. generate files, logging something, etc…) after all the writeBundle hooks across all environments have completed. Only the plugin controlling the build can perform such action.

The proposed solution

We’ve (the Cloudflare team) considered and discussed internally various different alternatives, but we settled on the following as it provides more flexibility and less downsides than any other alternative we considered.

The solution would be to make buildApp a hook rather than part of the config. Such a hook would run for each plugin sequentially and it could be defined as a function or an object with order and handler properties, as is common for other hooks.

A framework plugin would typically leave order unspecified whereas a platform plugin would typically set order to post. This convention would allow platforms to build additional environments and output configuration files required for deployment while allowing frameworks to get priority on the build process.

An additional builder.builtEnvironments property that is a Set containing the environments that have so far been built would also be made available (so that plugins could change behavior based on whether an environment has already been built or not).

Let’s see an example of this API where there are two plugins both being used, the first implementing a framework while the second targeting a platform for the application to be deployed to:

// framework plugin

async buildApp(builder) {
  // the plugin builds the various environments that it is targeting
  await builder.build('client');
  await builder.build('ssr');
  await builder.build(...);
}

// platform plugin

async buildApp: {
  // the plugin specifies the 'post' order since it doesn't require
  // precedence on the environments building process
  order: 'post',
  handler(builder) {
    // if there are environments configured by the plugin that
    //haven't already been  built then this is the right time to build those
    const environmentsToBuild = configuredEnvironments.filter(
      env => !builder.builtEnvironments.has(env.name);
    );
    await Promise.all(environmentsToBuild.map(env => builder.build(env)));

    // the plugin needs to run some extra logic after it knows
    // that all the environments have been built 
    generatePlatformSpecificArtifactsForDeployment();
  }
}

Advantages of this approach

The advantages of this approach are that such API:

• Would be similar to the current one, not drastically changing the environments API
• Would be very flexible, allowing different plugins to build and combine different environments how they see fit
• Allows different plugins to handle different parts of the build
• Allows building additional environments with knowledge of which environments have already been built
• Allows plugins to run logic after all builds have completed

Possible additions

It may also be worth considering adding a builder.clearEnvironment(environment.name) method to clear the built artifacts of an environments as some frameworks create a server build that is only used for prerendering. This wouldn’t necessarily need to be part of the initial API.

Alternatives

For completeness, here's a list of alternative solutions that we’ve considered, alongside explanations describing why we haven’t considered them as optimal as the proposed solution:

Adding a buildApp.targets config

Adding a targets config option such as:

 buildApp: {
    targets(environments) { return ['client', 'ssr'] }
    handler() { /* omit */ }
  }

(reference: #16358 (reply in thread))

This wouldn’t allow multiple plugins to potentially build the same environment and also would require extra coordination between framework and platform plugin

Pre and Post hooks

Adding some pre and post hooks around the existing buildApp config or something to that extent (basically in the same vein as #16358 (comment))

This seems to add unnecessary complexity over the proposed solution without any noticeable gain

Declarative build configs

buildApp hooks would take and return build configuration objects containing declarative information on which environments Vite needs to build and how, in the same vein as how the config hook works where each plugin is able to update, pass or override the config object in a very flexible manner.

This feels too different from the current environments API design, defining the build configuration objects would also be very involved.

buildEnvironment middleware hook

Each plugin could provide a buildAppEnvironment middleware hook that would get a promise or set of promises for the current environment builds and would return a promise that will be passed through to the next plugin in the chain, after the last middleware hook the environment could be built.

In this way each middleware can wrap the call to the next middleware with pre and post processing, but also await other builds before doing processing, a middleware would also be able to block a build from occurring at all by not calling the next middleware.

This could be an interesting API but it might require a complex mental model and implementation, the proposed solution seems simpler both to use and implement.

[patak-dev]

Thanks for the detailed proposal @dario-piotrowicz! I like the idea of making buildApp a hook. For reference, many has expressed support for the same needs triggering this API extension.

One idea we discussed long ago with @antfu when toying with making buildApp a hook, was to directly have is-built information on the environment themselves. I think the same could be achieved without the extra builder.builtEnvironments set in this way.

We could extend builder.build(environment) to build once and return the same promise after the first call. And also have an environment.isBuilt boolean if needed (the set can then be constructed from this flag). But even without the flag, you could get:

// framework plugin
async buildApp(builder) {
  await builder.build('client');
  await builder.build('ssr');
  await builder.build(...);
}

// platform plugin
async buildApp: {
  order: 'post',
  handler(builder) {
    const environmentsToBuild = builder.environments.filter(env =>
      configuredEnvironments.has(name === env.name);
    );
    // Safely call build again on all the environments that needs to be built,
    // not a problem to call the ones that have already been built 
    await Promise.all(environmentsToBuild.map(env => builder.build(env)));
    generatePlatformSpecificArtifactsForDeployment();
  }
}

This assumes that each environment only needs to be built once. But I think that is a safe assumption to make.

[dario-piotrowicz]

Thanks @patak-dev 😄

Yes both the flag and the promise api look very nice to me! I'd definitely be on board with that 🙂

my slight preference would be towards isBuilt I guess as that would allow an environment to be built more than once if really necessary for whatever reason, but as you said that's probably not really a valid/real use case, so it might not be a huge deal either way 🙂

[jamesopstad]

@patak-dev Do you think this change could be considered for the 7.0 milestone? It would make sense to introduce a breaking change like this in a new major, even though the Environment API is experimental. Perhaps it could be enabled with a flag before then to gather feedback.

[dario-piotrowicz]

mh... if this is going into Vite 7 why not simply introduce it as a breaking change? 🤔

[patak-dev]

Because it is easy to keep config.builder.buildApp working and I think it would help with the current explorations to avoid the breaking change. Others may disagree though, we can discuss it in the PR and change it before Vite 7.

[dario-piotrowicz]

ah ok I see thanks, I'm not strongly against having both but I just hope that that's not a long term solution as it sounds a bit unoptimal/awkward to me 🙂

[patak-dev]

Added a longer note to the description of the PR:

Note: I ended up not removing config.builder.buildApp because it is easy to keep working and I think it would help with the current explorations to avoid the breaking change. We can still decide to do a clean move to a hook only world in Vite 7 or delay that to Vite 8 (if the hook proves to be the final shape of the API, what I'm leaning towards). We can deprecate config.builder.buildApp at one point during Vite 7 then.

[dario-piotrowicz]

ok, that sounds perfect, thanks Patak 😄