Library / SDK
eirslett/frontend-maven-plugin avatar
eirslett/frontend-maven-plugin

frontend-maven-plugin pins Node inside the build instead of the machine

"Maven-node-grunt-gulp-npm-node-plugin to end all maven-node-grunt-gulp-npm-plugins." A Maven plugin that downloads/installs Node and NPM locally, runs NPM install, Grunt, Gulp and/or Karma.

4,381 stars867 forksJavaApache-2.0

At a glance

What is it?
A Maven plugin that downloads Node, npm, Yarn, Corepack or Bun into a project folder and runs the JavaScript build from there. The value is build reproducibility; the cost is that it refuses to reuse any Node already on the machine.
Who is it for?
Adopt frontend-maven-plugin when a backend Maven build has to produce the frontend bundle and the build agent has no Node runtime of its own, because it removes the need for global installs and makes the Node version a property of the pom.xml. Do not adopt it where CI images or toolchain managers already pin Node: the plugin will not touch an existing installation, so you would keep two sources of truth and pay the download cost on every cold build.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 25 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • eirslett/frontend-maven-plugin4,381 ★ · -2
Star history
Repository2026-09-232026-11-14
eirslett/frontend-maven-plugin4.4k4.4k

-2 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Node is unpacked into a node folder, not onto the machine

The plugin's central act is a download and extract. Node archives are fetched from https://nodejs.org/dist, npm tarballs from https://registry.npmjs.org/npm/-, and both are unpacked into a node folder created under the installation directory. Nothing is written to a global prefix and no PATH is modified, so a build agent with a perfectly good Node installation still gets its own private copy inside the project directory. The README is explicit that this local install will not interfere with any Node or npm already present.

That isolation is the whole point. The plugin lists three goals: keep frontend and backend builds separate down to one plugin boundary, use Node in the build without installing it globally, and guarantee that the Node and npm versions are identical in every build environment. The third goal is the one that changes how you work. A developer on a laptop and a continuous integration runner executing the same Maven build run the same Node and npm versions, because the version string in the pom.xml is the version that gets used.

The trade is that the plugin is deliberately not a Node installer for developers or production. The README states that frontend developers will still install Node on their own machines, and that the Node usage is for build-time tasks such as minification, obfuscation, compression, packaging and testing. Read that as a scope limit rather than a caveat.

install-node-and-npm binds to generate-resources by default

Declaring the plugin is ordinary Maven boilerplate. Put the coordinates in the plugins block of your pom.xml, replace the version placeholder with the newest version available under com/github/eirslett/frontend-maven-plugin in Maven Central, and bind a goal to a phase. The default phase for install-node-and-npm is generate-resources, so the runtime is in place before anything that compiles Java runs.

xml
<plugin>
    <groupId>com.github.eirslett</groupId>
    <artifactId>frontend-maven-plugin</artifactId>
    <version>LATEST_VERSION</version>
</plugin>

Binding the goal takes an execution block with an id, the goal name, and a phase. The id is optional and the phase can be omitted, since generate-resources is the default. After the runtime is unpacked, the npm goal runs install, and additional executions run npx, Grunt, Gulp, Karma, Webpack, Jspm, Bower, Yarn or Corepack against the local installation. The README makes a specific recommendation about how to wire those up: run your tasks through npm scripts rather than invoking each build tool as its own Maven execution, because a single npm script is one reproducible command instead of several executions whose order you have to maintain in the pom.xml.

One thing to do immediately after the first successful build is add the node folder to .gitignore, unless you actually want to commit it.

Node and npm have separate download roots, because they live in separate repositories

Air-gapped or proxied builds are handled with three configuration keys rather than one. nodeDownloadRoot points at wherever Node archives are mirrored, npmDownloadRoot does the same for npm tarballs, and serverId names an entry in your Maven settings.xml so the plugin can pick up credentials when the mirror requires authentication. Leaving nodeDownloadRoot unset means downloads come from https://nodejs.org/dist/, and leaving npmDownloadRoot unset means https://registry.npmjs.org/npm/-/.

xml
<configuration>
    <nodeDownloadRoot>http://myproxy.example.org/nodejs/</nodeDownloadRoot>
    <serverId>server001</serverId>
    <npmDownloadRoot>https://myproxy.example.org/npm/</npmDownloadRoot>
</configuration>

The split matters more than it first appears. Node and npm are stored in separate repositories, so a mirror that proxies only one of them leaves the other half of the install pointing straight at the public internet. The README names Nexus repository manager as a way to proxy the npm registry, and the separate roots are what let you route each dependency through the proxy your organisation already controls.

For Yarn the source changes again. Node still comes from https://nodejs.org/dist, but Yarn is fetched from a different host entirely. Yarn Berry projects need a Yarn 1.x install as a bootstrap, since the project pins its own Yarn version per project. The practical consequence is that a build behind a strict egress policy has three or four hostnames to allow, and each one is configurable but none of them are bundled.

Skipping a goal and ignoring its failure are different switches

Two configuration options decide whether a failure stops the build, and they are easy to confuse. The README lists a skipping-execution option and an ignoring-failure option under its optional configuration.

Alongside those sit a working directory setting that relocates where npm, Grunt or Karma execute, and an environment variables setting that injects values into those child processes. The working directory is the one to watch. Because Node lives in the installation directory and your sources may not, a task that shells out to a local binary can resolve the wrong path or none at all if the working directory does not point at the module root.

If an install fails midway, treat the node folder as disposable and delete it between attempts rather than trying to repair it.

The plugin refuses to reuse a Node that is already installed

The most consequential limitation is stated in a single notice near the top of the README: this plugin does not support already installed Node or npm versions, and the documented substitute is the exec-maven-plugin. There is no flag to point it at a system runtime, no detection that swaps in what is on PATH. Every build downloads its own copy, which means every cold build on every new agent pays the download and extract cost.

That design has a second edge. If your organisation provisions Node through a CI image, a base Docker layer or a toolchain manager such as one driven by a version file, this plugin will ignore all of it and fetch the version you wrote in the pom.xml. You end up maintaining the Node version in two places, and the pom.xml becomes the one that wins. Teams that have already standardised Node installation this way gain little and lose the ability to patch a runtime vulnerability by rebuilding an image.

Node and npm versions are also coupled differently depending on the major version. With Node above 4.0.0 the npm bundled with the release is used, which is what most projects want, since npm ships with Node.

A Java 17 and Maven 3.6 floor blocks older build agents

Requirements are listed plainly: Maven 3.6 and Java 17, and Maven 2 users are sent to the project wiki. That leaves the plugin's own documentation treating anything below 3.6 as out of scope, with Maven 4 mentioned without a tested matrix.

That floor is worth checking against your build image before anything else. A team still on Java 8 or Java 11 cannot adopt this plugin at its current requirement without a toolchain upgrade, which makes this less of a drop-in build plugin and more of a coordinated change.

exec-maven-plugin takes the opposite approach: use what is already there

The alternative the README itself names is the exec-maven-plugin, and the difference in approach is direct. exec-maven-plugin runs arbitrary commands, including npm and its scripts, against whatever runtime the machine provides. It has no opinion about which Node version that is and no download step of its own. Reproducibility moves from the plugin's configuration into your CI image or your own provisioning step.

That trade is worth naming honestly. If your organisation already pins Node in a Docker image, or you use a toolchain manager that reads a version file committed next to package.json, exec-maven-plugin costs you nothing in download time and keeps exactly one place where the Node version is defined. frontend-maven-plugin wins in the opposite case, where a backend developer or a stock CI runner has no Node at all and installing one globally would be the alternative.

Newer frontend tooling sits outside this plugin's own recommendation as well. The README says to prefer npm scripts over invoking individual tools, and modern build steps such as Vite are normally driven through a script named in package.json rather than through a dedicated Maven goal. Running them means adding an execution that calls the local npm, which is exactly the pattern this plugin is built around.

Editorial conclusion

Adopt frontend-maven-plugin when a backend Maven build has to produce the frontend bundle and the build agent has no Node runtime of its own, because it removes the need for global installs and makes the Node version a property of the pom.xml. Do not adopt it where CI images or toolchain managers already pin Node: the plugin will not touch an existing installation, so you would keep two sources of truth and pay the download cost on every cold build. Verify first that your proxy or Nexus can serve https://nodejs.org/dist and the npm registry tarballs, and that the build agent already meets the Java 17 and Maven 3.6 requirement.

Frequently asked questions

What is frontend-maven-plugin?

It is a Maven plugin that downloads and installs Node and npm into a folder inside your project, then runs npm install and any combination of tools such as Grunt, Gulp, Karma, Webpack, Jspm or Bower. Nothing is installed globally, so builds do not depend on what happens to be on the machine.

What is an alternative to frontend-maven-plugin?

The README names the exec-maven-plugin as the substitute when you want to use a Node or npm version that is already installed. Unlike this plugin, it performs no download and leaves the runtime version entirely to the build environment.

Which Java and Maven versions does frontend-maven-plugin require?

Maven 3.6 and Java 17 are the stated requirements. Maven 2 users are pointed at the project wiki instead.

Official sources

  1. eirslett/frontend-maven-plugin on GitHub
  2. Issues
  3. License: Apache-2.0
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/eirslett-frontend-maven-plugin.svg)](https://hysenlabs.com/projects/eirslett-frontend-maven-plugin)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/eirslett-frontend-maven-plugin.svg)](https://hysenlabs.com/projects/eirslett-frontend-maven-plugin)

Was this useful?