feat: add npm.excludePostinstallPackages option (#24421) (CP: 25.1) (#24442)

This PR cherry-picks changes from the original PR #24421 to branch 25.1.
---
#### Original PR description
> Adds a configuration option to exclude packages from running
postinstall scripts. Mirrors the existing npm.postinstallPackages
add-list and applies to both the built-in default entries (e.g. esbuild,
@vaadin/vaadin-usage-statistics) and any packages added via
postinstallPackages. Wired through Options, the Maven and Gradle
plugins, and DevModeInitializer.
> 
> Refs #24333
>

Co-authored-by: Tomi Virtanen <tltv@vaadin.com>

Author: vaadin-bot

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/Options.java

@@ -148,6 +148,11 @@ public class Options implements Serializable {
      */
     private List<String> postinstallPackages = new ArrayList<>();
 
+    /**
+     * Npm packages to exclude from running postinstall scripts.
+     */
+    private List<String> excludePostinstallPackages = new ArrayList<>();
+
     private FeatureFlags featureFlags;
 
     private boolean frontendHotdeploy = false;
@@ -698,6 +703,23 @@ public Options withPostinstallPackages(List<String> postinstallPackages) {
         return this;
     }
 
+    /**
+     * Sets the npm packages to exclude from running {@code postinstall} for.
+     * <p>
+     * Entries here are removed from the built-in default postinstall list (e.g.
+     * {@code esbuild}, {@code @vaadin/vaadin-usage-statistics}) as well as from
+     * any additional packages added via {@link #withPostinstallPackages(List)}.
+     *
+     * @param excludePostinstallPackages
+     *            the npm packages to exclude from postinstall
+     * @return the builder, for chaining
+     */
+    public Options withExcludePostinstallPackages(
+            List<String> excludePostinstallPackages) {
+        this.excludePostinstallPackages = excludePostinstallPackages;
+        return this;
+    }
+
     /**
      * Get the npm folder used for this build.
      *
@@ -925,6 +947,10 @@ public List<String> getPostinstallPackages() {
         return postinstallPackages;
     }
 
+    public List<String> getExcludePostinstallPackages() {
+        return excludePostinstallPackages;
+    }
+
     /**
      * Set to true to skip dev bundle build in case a dev bundle exists.
      * <p>

flow-build-tools/src/main/java/com/vaadin/flow/server/frontend/TaskRunNpmInstall.java

@@ -383,6 +383,7 @@ private void runNpmInstall() throws ExecutionFailedException {
         postinstallPackages.add("esbuild");
         postinstallPackages.add("@vaadin/vaadin-usage-statistics");
         postinstallPackages.addAll(options.getPostinstallPackages());
+        postinstallPackages.removeAll(options.getExcludePostinstallPackages());
 
         for (String postinstallPackage : postinstallPackages) {
             File packageJsonFile = getPackageJsonForModule(postinstallPackage);

flow-build-tools/src/test/java/com/vaadin/flow/server/frontend/TaskRunPnpmInstallTest.java

@@ -354,6 +354,23 @@ void runPnpmInstall_postInstall_runForDefinedAdditionalPackages()
                 "Postinstall for 'foo' was not run");
     }
 
+    @Test
+    void runPnpmInstall_postInstall_excludedBuiltinPackageIsSkipped()
+            throws ExecutionFailedException, IOException {
+        setupPostinstallPackages();
+        options.withExcludePostinstallPackages(
+                List.of("@vaadin/vaadin-usage-statistics"));
+        TaskRunNpmInstall task = createTask();
+        task.execute();
+
+        assertFalse(
+                new File(
+                        new File(options.getNodeModulesFolder(),
+                                "@vaadin/vaadin-usage-statistics"),
+                        "postinstall-file.txt").exists(),
+                "Postinstall for '@vaadin/vaadin-usage-statistics' should have been skipped");
+    }
+
     // https://github.com/vaadin/flow/issues/17663
     @Test
     @Timeout(30)

flow-plugins/flow-dev-bundle-plugin/src/main/java/com/vaadin/flow/plugin/maven/BuildDevBundleMojo.java

@@ -183,6 +183,15 @@ public class BuildDevBundleMojo extends AbstractMojo
     @Parameter(property = "npm.postinstallPackages", defaultValue = "")
     private List<String> postinstallPackages;
 
+    /**
+     * Npm packages to exclude from running post install scripts.
+     * <p>
+     * Used to skip built-in entries (e.g. {@code esbuild}) when their
+     * postinstall step is known to fail or is not needed.
+     */
+    @Parameter(property = "npm.excludePostinstallPackages", defaultValue = "")
+    private List<String> excludePostinstallPackages;
+
     @Parameter(property = InitParameters.REACT_ENABLE, defaultValue = "true")
     private boolean reactEnable;
 
@@ -516,6 +525,11 @@ public List<String> postinstallPackages() {
         return postinstallPackages;
     }
 
+    @Override
+    public List<String> excludePostinstallPackages() {
+        return excludePostinstallPackages;
+    }
+
     @Override
     public boolean isFrontendHotdeploy() {
         return false;

flow-plugins/flow-gradle-plugin/src/main/kotlin/com/vaadin/gradle/GradlePluginAdapter.kt

@@ -276,6 +276,9 @@ internal class GradlePluginAdapter private constructor(
     override fun postinstallPackages(): List<String> =
         config.postinstallPackages.get()
 
+    override fun excludePostinstallPackages(): List<String> =
+        config.excludePostinstallPackages.get()
+
     override fun isFrontendHotdeploy(): Boolean = config.frontendHotdeploy.get()
 
     override fun ciBuild(): Boolean = config.ciBuild.get()

flow-plugins/flow-gradle-plugin/src/main/kotlin/com/vaadin/gradle/PrepareFrontendInputProperties.kt

@@ -143,6 +143,10 @@ internal class PrepareFrontendInputProperties(
     fun getPostInstallPackages(): ListProperty<String> =
         config.postinstallPackages
 
+    @Input
+    fun getExcludePostInstallPackages(): ListProperty<String> =
+        config.excludePostinstallPackages
+
     @Input
     fun getFrontendHotdeploy(): Provider<Boolean> = config.frontendHotdeploy
 

flow-plugins/flow-gradle-plugin/src/main/kotlin/com/vaadin/gradle/VaadinFlowPluginExtension.kt

@@ -236,6 +236,13 @@ public abstract class VaadinFlowPluginExtension @Inject constructor(private val
      */
     public abstract val postinstallPackages: ListProperty<String>
 
+    /**
+     * Defines the npm packages to exclude from running postinstall scripts.
+     * Used to skip built-in entries (e.g. `esbuild`) when their postinstall
+     * step is known to fail or is not needed.
+     */
+    public abstract val excludePostinstallPackages: ListProperty<String>
+
     public val classpathFilter: ClasspathFilter = ClasspathFilter()
 
     /**
@@ -556,6 +563,10 @@ public class PluginEffectiveConfiguration(
         extension.postinstallPackages
             .convention(listOf())
 
+    public val excludePostinstallPackages: ListProperty<String> =
+        extension.excludePostinstallPackages
+            .convention(listOf())
+
     public val classpathFilter: ClasspathFilter = extension.classpathFilter
 
     public val processResourcesTaskName: Property<String> =
@@ -728,6 +739,7 @@ public class PluginEffectiveConfiguration(
             "resourceOutputDirectory=${resourceOutputDirectory.get()}, " +
             "projectBuildDir=${projectBuildDir.get()}, " +
             "postinstallPackages=${postinstallPackages.get()}, " +
+            "excludePostinstallPackages=${excludePostinstallPackages.get()}, " +
             "sourceSetName=${sourceSetName.get()}, " +
             "dependencyScope=${dependencyScope.get()}, " +
             "processResourcesTaskName=${processResourcesTaskName.get()}, " +

flow-plugins/flow-maven-plugin/src/main/java/com/vaadin/flow/plugin/maven/FlowModeAbstractMojo.java

@@ -247,6 +247,15 @@ public abstract class FlowModeAbstractMojo extends AbstractMojo
     @Parameter(property = "npm.postinstallPackages", defaultValue = "")
     private List<String> postinstallPackages;
 
+    /**
+     * Npm packages to exclude from running post install scripts.
+     * <p>
+     * Used to skip built-in entries (e.g. {@code esbuild}) when their
+     * postinstall step is known to fail or is not needed.
+     */
+    @Parameter(property = "vaadin.npm.excludePostinstallPackages", defaultValue = "")
+    private List<String> excludePostinstallPackages;
+
     /**
      * Parameter to control if frontend development server should be used in
      * development mode or not.
@@ -692,6 +701,11 @@ public List<String> postinstallPackages() {
         return postinstallPackages;
     }
 
+    @Override
+    public List<String> excludePostinstallPackages() {
+        return excludePostinstallPackages;
+    }
+
     @Override
     public boolean isFrontendHotdeploy() {
         if (frontendHotdeploy != null) {

flow-plugins/flow-maven-plugin/src/test/java/com/vaadin/flow/plugin/maven/BuildFrontendMojoTest.java

@@ -199,6 +199,8 @@ void setup() throws Exception {
                 Paths.get(projectBase.toString(), "target").toString());
         ReflectionUtils.setVariableValueInObject(mojo, "postinstallPackages",
                 Collections.emptyList());
+        ReflectionUtils.setVariableValueInObject(mojo,
+                "excludePostinstallPackages", Collections.emptyList());
         Mockito.doReturn(
                 Set.of(jarResourcesSource.getParentFile().getParentFile()))
                 .when(mojo).getJarFiles();

flow-plugins/flow-plugin-base/src/main/java/com/vaadin/flow/plugin/base/BuildFrontendUtil.java

@@ -363,6 +363,8 @@ public static void runNodeUpdater(PluginAdapterBuild adapter,
                     .withNodeDownloadRoot(nodeDownloadRootURI)
                     .setJavaResourceFolder(adapter.javaResourceFolder())
                     .withPostinstallPackages(adapter.postinstallPackages())
+                    .withExcludePostinstallPackages(
+                            adapter.excludePostinstallPackages())
                     .withCiBuild(adapter.ciBuild())
                     .withForceProductionBuild(adapter.forceProductionBuild())
                     .withReact(adapter.isReactEnabled())
@@ -440,6 +442,8 @@ public static void runDevBuildNodeUpdater(PluginAdapterBuild adapter)
                     .withNodeDownloadRoot(nodeDownloadRootURI)
                     .setJavaResourceFolder(adapter.javaResourceFolder())
                     .withPostinstallPackages(adapter.postinstallPackages())
+                    .withExcludePostinstallPackages(
+                            adapter.excludePostinstallPackages())
                     .withBundleBuild(true)
                     .skipDevBundleBuild(adapter.skipDevBundleBuild())
                     .withCompressBundle(adapter.compressBundle())