> Markdown version of [Node.js](https://vaadin.com/docs/next/flow/configuration/development-mode/node-js). Section index: [llms.txt](https://vaadin.com/docs/next/flow/llms.txt)

# <a id="node.installation"></a>Configuring Node.js

Vaadin uses the Node.js runtime in development mode to run the Vite development server, as well as the Node.js package manager (i.e., `npm`) and package runner (i.e., `npx`) to fetch, install, and run frontend packages.

## <a id="installation"></a>Installation

Node.js can be installed in two ways: it can be installed automatically by Vaadin into the user’s home directory, or it can be installed globally with a downloaded installer or package manager, such as Homebrew.

For global installation, Node.js can be downloaded from `https://nodejs.org/en/download/`. You should use the latest Long-Term Support (LTS) version.

### <a id="automatic-installation"></a>Automatic Installation

When Vaadin installs Node.js automatically, it extracts the complete Node.js distribution into a version-specific directory under `~/.vaadin/`. For example, if the requested version is `v24.14.0`, it’s installed into `~/.vaadin/node-v24.14.0/`.

The full distribution is extracted, including `node`, `npm`, `npx`, and `corepack` on Unix, or `node.exe`, `npm.cmd`, `npx.cmd`, and `corepack.cmd` on Windows. This means you can use `npm`, `npx`, and `corepack` directly from the installation directory if needed. For example:

```terminal
~/.vaadin/node-v24.14.0/bin/npm install some-package
~/.vaadin/node-v24.14.0/bin/npx some-tool
```

On Windows, the executables are in the root of the installation directory:

```terminal
%USERPROFILE%\.vaadin\node-v24.14.0\npm.cmd install some-package
%USERPROFILE%\.vaadin\node-v24.14.0\npx.cmd some-tool
```

Since each version is installed into its own directory, multiple Node.js versions can coexist side by side under `~/.vaadin/`.

### <a id="removing-unused-installations"></a>Removing Unused Installations (since V25.3)

Every Node.js version a project has needed stays under `~/.vaadin/`, which adds up over the years. Vaadin cleans up after itself: each installation records when it was last taken into use, and the ones unused for six months are removed the next time a new version is installed. Downloaded archives are removed as well, including the ones earlier Vaadin versions left behind next to the unpacked installation.

The cleanup stays on the safe side:

- Only directories and archives named like an automatically installed Node.js are touched. Anything else under `~/.vaadin/` is left alone.

- The installation in use is never removed, and neither is the last remaining one, so the folder always keeps at least one version.

- An installation whose last use isn’t known yet is kept, and its six months start from the moment Vaadin first sees it.

### <a id="resolution-order"></a>Resolution Order

Vaadin resolves which Node.js installation to use in the following order:

1. If [`node.folder`](#node-folder) is set, use exclusively that directory. If the Node.js binary isn’t found there, the build fails with no fallback.

2. If `require.home.node` is *not* set, check for a suitable global Node.js on the system `PATH`.

3. Check `~/.vaadin/` for the exact requested version (e.g., `~/.vaadin/node-v24.14.0/`).

4. Fall back to any compatible installed version found in `~/.vaadin/`.

5. If nothing is found, download and install the requested version into `~/.vaadin/node-v<version>/`.

You can force Vaadin to skip global Node.js and use its own installation by setting the `require.home.node` property to `true`. See [Configuration Properties](https://vaadin.com/docs/next/flow/configuration/properties.md) for more information.

### <a id="node-folder"></a>Custom Node.js Folder

You can point Vaadin to a specific Node.js installation directory by setting the `node.folder` property. When this property is set, Vaadin uses Node.js exclusively from the specified folder. No fallback to `~/.vaadin/` or global Node.js occurs — if the binary isn’t found in the given folder, the build fails.

This is useful when you want full control over which Node.js installation is used, for example in CI/CD environments or when using a Node.js version manager.

To set this as a system property:

```bash
mvn jetty:run -Dvaadin.node.folder=/usr/local/custom-node
```

Or as a Maven plugin configuration:

```xml
<configuration>
    <nodeFolder>/usr/local/custom-node</nodeFolder>
</configuration>
```

## <a id="proxy-settings-for-downloading-frontend-toolchain"></a>Proxy Settings for Downloading Frontend Toolchain

If you’re operating behind a proxy server, you should configure your proxy settings so that Vaadin can use them to download the frontend toolchain. Vaadin reads proxy settings from four places; you can set the proxy data in any of the following:

- System properties;

- `{project directory}/.npmrc` file;

- `{user home directory}/.npmrc` file; or

- Environment variables.

The settings are read in this order. For example, if you set the proxy in the system properties, the other sources are ignored.

The keys that you should use to define proxy settings are as follows:

| In System Properties & Environment Variables | In .npmrc Files | Description                                                                        |
| -------------------------------------------- | --------------- | ---------------------------------------------------------------------------------- |
| `HTTP_PROXY`                                 | `proxy`         | A proxy to use for outgoing HTTP requests.                                         |
| `HTTPS_PROXY`                                | `https-proxy`   | A proxy to use for outgoing HTTPS requests.                                        |
| `NOPROXY`                                    | `noproxy`       | A comma-separated string of domain extensions for which a proxy shouldn’t be used. |

The `.npmrc` file structure is `ini` — like Java properties files. It includes key-values pairs separated by the equal-sign (i.e., `=`).

Here’s an example of the content of such a file with proxy settings:

```
proxy=http://myusername:s3cr3tpassw0rd@proxyserver1:8085
https-proxy=http://myusername:s3cr3tpassw0rd@proxyserver1:8086
noproxy=192.168.1.1,vaadin.com,mycompany.com
```

When using PNPM and customizing the `.npmrc` file auto-generated by Vaadin, make sure to remove the `NOTICE: this is an auto-generated file` comment to prevent Vaadin to overwrite it with the default contents.

To learn more about the `.npmrc` file, see the [official npmrc documentation](https://docs.npmjs.com/configuring-npm/npmrc).

> **Note:** Starting from Java 8u111, basic authentication for HTTPS tunneling is disabled by default, and the download of Node.js may fail if proxy configuration provides user credentials. See "Disable Basic authentication for HTTPS tunneling" in the [JDK 8u111 release notes](https://www.oracle.com/java/technologies/javase/8u111-relnotes.html) for more on this.
>
> To get the download to work, it’s necessary to add the `-Djdk.http.auth.tunneling.disabledSchemes=""` system property to the IDE application run configuration, or to the build tool — Maven or Gradle — command-line.

`33A25C64-2E6E-4F6F-9C0E-5EEFD244D4B3`