feat: Install Node.js in version-specific directories with fallback support

- Install Node.js to version-specific directories (e.g., node-v24.10.0/)
  instead of a single node/ directory to support multiple versions
- Add fallback logic to use existing compatible Node.js installation
  when the requested version is not available
- Scan install directory for node-v* folders, filter by minimum
  supported version (24.0), and select the newest compatible version
- Make FrontendTools.SUPPORTED_NODE_VERSION public for reuse
- Add FileIOUtils.copyDirectory() and delete() methods

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/server/frontend/FrontendTools.java

@@ -119,7 +119,7 @@ public class FrontendTools {
     private static final int SUPPORTED_NPM_MAJOR_VERSION = 11;
     private static final int SUPPORTED_NPM_MINOR_VERSION = 3;
 
-    static final FrontendVersion SUPPORTED_NODE_VERSION = new FrontendVersion(
+    public static final FrontendVersion SUPPORTED_NODE_VERSION = new FrontendVersion(
             SUPPORTED_NODE_MAJOR_VERSION, SUPPORTED_NODE_MINOR_VERSION);
 
     private static final FrontendVersion SUPPORTED_NPM_VERSION = new FrontendVersion(

flow-server/src/main/java/com/vaadin/flow/server/frontend/installer/NodeInstaller.java

@@ -36,6 +36,7 @@
 import com.vaadin.flow.internal.MessageDigestUtil;
 import com.vaadin.flow.internal.Pair;
 import com.vaadin.flow.server.frontend.FileIOUtils;
+import com.vaadin.flow.server.frontend.FrontendTools;
 import com.vaadin.flow.server.frontend.FrontendUtils;
 import com.vaadin.flow.server.frontend.FrontendVersion;
 import com.vaadin.frontendtools.installer.ArchiveExtractionException;
@@ -53,14 +54,10 @@
  */
 public class NodeInstaller {
 
-    public static final String INSTALL_PATH = "/node";
+    public static final String INSTALL_PATH_PREFIX = "/node";
 
     public static final String SHA_SUMS_FILE = "SHASUMS256.txt";
 
-    private static final String NODE_WINDOWS = INSTALL_PATH.replaceAll("/",
-            "\\\\") + "\\node.exe";
-    private static final String NODE_DEFAULT = INSTALL_PATH + "/node";
-
     public static final String PROVIDED_VERSION = "provided";
 
     private static final int MAX_DOWNLOAD_ATTEMPS = 5;
@@ -74,6 +71,11 @@ public class NodeInstaller {
 
     private String npmVersion = PROVIDED_VERSION;
     private String nodeVersion;
+    /**
+     * The actual node version being used. May differ from nodeVersion if a
+     * compatible fallback version was found.
+     */
+    private String activeNodeVersion;
     private URI nodeDownloadRoot;
     private String userName;
     private String password;
@@ -234,9 +236,9 @@ public void install() throws InstallationException {
     }
 
     private boolean nodeIsAlreadyInstalled() throws InstallationException {
-        File nodeFile = getNodeExecutable();
+        // First, check if the exact requested version is installed
+        File nodeFile = getNodeExecutableForVersion(nodeVersion);
         if (nodeFile.exists()) {
-
             List<String> nodeVersionCommand = new ArrayList<>();
             nodeVersionCommand.add(nodeFile.toString());
             nodeVersionCommand.add("--version");
@@ -245,17 +247,101 @@ private boolean nodeIsAlreadyInstalled() throws InstallationException {
 
             if (version.equals(nodeVersion)) {
                 getLogger().info("Node {} is already installed.", version);
+                activeNodeVersion = nodeVersion;
                 return true;
             } else {
                 getLogger().info(
                         "Node {} was installed, but we need version {}",
                         version, nodeVersion);
-                return false;
             }
         }
+
+        // Check if any other compatible version is available
+        String fallbackVersion = findCompatibleInstalledVersion();
+        if (fallbackVersion != null) {
+            getLogger().debug("Using existing Node {} instead of installing {}",
+                    fallbackVersion, nodeVersion);
+            activeNodeVersion = fallbackVersion;
+            return true;
+        }
+
         return false;
     }
 
+    /**
+     * Scans the install directory for installed Node.js versions and returns
+     * the newest one that is supported.
+     *
+     * @return the version string (e.g., "v24.10.0") of the best available
+     *         version, or null if none found
+     */
+    private String findCompatibleInstalledVersion() {
+        if (!installDirectory.exists() || !installDirectory.isDirectory()) {
+            return null;
+        }
+
+        File[] nodeDirs = installDirectory.listFiles(file -> file.isDirectory()
+                && file.getName().startsWith("node-v"));
+
+        if (nodeDirs == null || nodeDirs.length == 0) {
+            return null;
+        }
+
+        FrontendVersion bestVersion = null;
+        String bestVersionString = null;
+
+        for (File nodeDir : nodeDirs) {
+            String dirName = nodeDir.getName();
+            // Extract version from directory name (node-v24.10.0 -> v24.10.0)
+            String versionString = dirName.substring("node-".length());
+
+            try {
+                FrontendVersion version = new FrontendVersion(versionString);
+
+                // Skip versions older than minimum supported
+                if (version.isOlderThan(FrontendTools.SUPPORTED_NODE_VERSION)) {
+                    getLogger().debug(
+                            "Skipping {} - older than minimum supported {}",
+                            versionString, FrontendTools.SUPPORTED_NODE_VERSION
+                                    .getFullVersion());
+                    continue;
+                }
+
+                // Verify the node executable actually exists and works
+                File nodeExecutable = getNodeExecutableForVersion(
+                        versionString);
+                if (!nodeExecutable.exists()) {
+                    getLogger().debug(
+                            "Skipping {} - executable not found at {}",
+                            versionString, nodeExecutable);
+                    continue;
+                }
+
+                // Keep the newest version
+                if (bestVersion == null || version.isNewerThan(bestVersion)) {
+                    bestVersion = version;
+                    bestVersionString = versionString;
+                }
+            } catch (NumberFormatException e) {
+                getLogger().debug("Could not parse version from directory: {}",
+                        dirName);
+            }
+        }
+
+        return bestVersionString;
+    }
+
+    /**
+     * Gets the node executable path for a specific version.
+     */
+    private File getNodeExecutableForVersion(String version) {
+        String versionedPath = INSTALL_PATH_PREFIX + "-" + version;
+        String nodeExecutable = platform.isWindows()
+                ? versionedPath.replaceAll("/", "\\\\") + "\\node.exe"
+                : versionedPath + "/bin/node";
+        return new File(installDirectory + nodeExecutable);
+    }
+
     private void installNode(InstallData data) throws InstallationException {
         try {
 
@@ -285,6 +371,7 @@ private void installNode(InstallData data) throws InstallationException {
         }
 
         getLogger().info("Local node installation successful.");
+        activeNodeVersion = nodeVersion;
     }
 
     private void installNodeUnix(InstallData data)
@@ -424,7 +511,18 @@ public String getInstallDirectory() {
     }
 
     private File getInstallDirectoryFile() {
-        return new File(installDirectory, INSTALL_PATH);
+        return new File(installDirectory, getVersionedInstallPath());
+    }
+
+    private String getVersionedInstallPath() {
+        // Use activeNodeVersion if set (fallback version), otherwise use
+        // requested nodeVersion
+        String version = activeNodeVersion != null ? activeNodeVersion
+                : nodeVersion;
+        if (version == null || PROVIDED_VERSION.equals(version)) {
+            return INSTALL_PATH_PREFIX;
+        }
+        return INSTALL_PATH_PREFIX + "-" + version;
     }
 
     private File getNodeInstallDirectory() {
@@ -627,17 +725,6 @@ private void verifyArchive(File archive)
         }
     }
 
-    /**
-     * Get node executable file.
-     *
-     * @return node executable
-     */
-    private File getNodeExecutable() {
-        String nodeExecutable = platform.isWindows() ? NODE_WINDOWS
-                : NODE_DEFAULT;
-        return new File(installDirectory + nodeExecutable);
-    }
-
     private static FrontendVersion getVersion(String tool,
             List<String> versionCommand) throws InstallationException {
         try {

flow-server/src/test/java/com/vaadin/flow/server/frontend/installer/NodeInstallerTest.java

@@ -105,8 +105,10 @@ public void installNodeFromFileSystem_NodeIsInstalledToTargetDirectory()
             }
         }
 
-        // add a file to node/node_modules_npm that should be cleaned out
-        File nodeDirectory = new File(targetDir, "node");
+        // add a file to node-{version}/node_modules_npm that should be cleaned
+        // out
+        String versionedNodeDir = "node-" + FrontendTools.DEFAULT_NODE_VERSION;
+        File nodeDirectory = new File(targetDir, versionedNodeDir);
         String nodeModulesPath = platform.isWindows() ? "node_modules"
                 : "lib/node_modules";
         File nodeModulesDirectory = new File(nodeDirectory, nodeModulesPath);
@@ -133,11 +135,12 @@ public void installNodeFromFileSystem_NodeIsInstalledToTargetDirectory()
             throw new IllegalStateException("Failed to install Node", e);
         }
 
-        Assert.assertTrue("npm should have been copied to node_modules",
-                new File(targetDir, "node/" + nodeExec).exists());
+        Assert.assertTrue("node should have been installed",
+                new File(targetDir, versionedNodeDir + "/" + nodeExec)
+                        .exists());
         String npmInstallPath = platform.isWindows()
-                ? "node/node_modules/npm/bin/npm"
-                : "node/lib/node_modules/npm/bin/npm";
+                ? versionedNodeDir + "/node_modules/npm/bin/npm"
+                : versionedNodeDir + "/lib/node_modules/npm/bin/npm";
         Assert.assertTrue("npm should have been copied to node_modules",
                 new File(targetDir, npmInstallPath).exists());
         Assert.assertFalse("old npm files should have been removed",
@@ -146,4 +149,88 @@ public void installNodeFromFileSystem_NodeIsInstalledToTargetDirectory()
                 "old style node_modules files should have been removed",
                 oldGarbage.exists());
     }
+
+    @Test
+    public void fallbackToExistingCompatibleVersion() throws IOException {
+        Platform platform = Platform.guess();
+        String nodeExec = platform.isWindows() ? "node.exe" : "node";
+
+        File targetDir = new File(baseDir + "/installation");
+
+        // Pre-install an older but compatible version (v24.8.0)
+        String existingVersion = "v24.8.0";
+        String existingVersionDir = "node-" + existingVersion;
+        File existingNodeDir = new File(targetDir, existingVersionDir);
+        File existingBinDir = platform.isWindows() ? existingNodeDir
+                : new File(existingNodeDir, "bin");
+        FileUtils.forceMkdir(existingBinDir);
+        File existingNodeExec = new File(existingBinDir, nodeExec);
+        Assert.assertTrue("Existing node executable should be created",
+                existingNodeExec.createNewFile());
+
+        // Request a newer version that doesn't exist
+        String requestedVersion = "v24.99.0";
+
+        NodeInstaller nodeInstaller = new NodeInstaller(targetDir,
+                Collections.emptyList()).setNodeVersion(requestedVersion)
+                .setNodeDownloadRoot(new File(baseDir).toPath().toUri());
+
+        // The install should succeed by falling back to v24.8.0
+        try {
+            nodeInstaller.install();
+        } catch (InstallationException e) {
+            // Expected - download will fail, but fallback should work
+            Assert.fail(
+                    "Should have used fallback version instead of trying to download: "
+                            + e.getMessage());
+        }
+
+        // Verify that the install directory points to the fallback version
+        Assert.assertEquals(
+                "Install directory should point to fallback version",
+                new File(targetDir, existingVersionDir).getPath(),
+                nodeInstaller.getInstallDirectory());
+    }
+
+    @Test
+    public void fallbackSelectsNewestCompatibleVersion() throws IOException {
+        Platform platform = Platform.guess();
+        String nodeExec = platform.isWindows() ? "node.exe" : "node";
+
+        File targetDir = new File(baseDir + "/installation");
+
+        // Pre-install multiple versions
+        for (String version : new String[] { "v24.5.0", "v24.8.0", "v24.6.0",
+                "v23.0.0" }) {
+            String versionDir = "node-" + version;
+            File nodeDir = new File(targetDir, versionDir);
+            File binDir = platform.isWindows() ? nodeDir
+                    : new File(nodeDir, "bin");
+            FileUtils.forceMkdir(binDir);
+            File nodeExecFile = new File(binDir, nodeExec);
+            nodeExecFile.createNewFile();
+        }
+
+        // Request a version that doesn't exist
+        String requestedVersion = "v24.99.0";
+
+        NodeInstaller nodeInstaller = new NodeInstaller(targetDir,
+                Collections.emptyList()).setNodeVersion(requestedVersion)
+                .setNodeDownloadRoot(new File(baseDir).toPath().toUri());
+
+        try {
+            nodeInstaller.install();
+        } catch (InstallationException e) {
+            Assert.fail(
+                    "Should have used fallback version instead of trying to download: "
+                            + e.getMessage());
+        }
+
+        // Verify that the newest compatible version (v24.8.0) was selected
+        // Note: v23.0.0 should be skipped as it's below minimum supported
+        // version
+        Assert.assertEquals("Should select newest compatible version (v24.8.0)",
+                new File(targetDir, "node-v24.8.0").getPath(),
+                nodeInstaller.getInstallDirectory());
+    }
 }