frontend-maven-plugin

This plugin downloads/installs Node and NPM locally for your project, runs npm install, and then any combination of Bower, Grunt, Gulp, Jspm, Karma, or Webpack. It's supposed to work on Windows, OS X and Linux.

If you prefer Yarn over NPM for your node package fetching, this plugin can also download Node and Yarn and then run yarn install for your project.

What is this plugin meant to do?

• Let you keep your frontend and backend builds as separate as possible, by reducing the amount of interaction between them to the bare minimum; using only 1 plugin.
• Let you use Node.js and its libraries in your build process without installing Node/NPM globally for your build system
• Let you ensure that the version of Node and NPM being run is the same in every build environment

What is this plugin not meant to do?

• Not meant to replace the developer version of Node - frontend developers will still install Node on their laptops, but backend developers can run a clean build without even installing Node on their computer.
• Not meant to install Node for production uses. The Node usage is intended as part of a frontend build, running common javascript tasks such as minification, obfuscation, compression, packaging, testing etc.

Notice: This plugin does not support already installed Node or npm versions. Use the exec-maven-plugin instead.

Requirements

• Maven 3.6 and Java 17
• Maven 4 seems to work fine with this plugin. (Feel free to report any issues.)
• For Maven 2 support take a look at the wiki.

Installation

Include the plugin as a dependency in your Maven project. Change LATEST_VERSION to the latest tagged version.

<plugins>
    <plugin>
        <groupId>com.github.eirslett</groupId>
        <artifactId>frontend-maven-plugin</artifactId>

        <version>LATEST_VERSION</version>
        ...
    </plugin>
...

Usage

Have a look at the example project, to see how it should be set up: https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/example%20project/pom.xml

• frontend-maven-plugin - What is this plugin meant to do? - What is this plugin not meant to do?
• Requirements
• Installation
• Usage
  • Installing node and npm
  • Installing node and yarn
  • Installing node and corepack
  • Installing bun
  • Running npm
  • npx
  • Running yarn
  • Yarn with Private Registry
  • Running corepack
  • Running bower
  • Running Grunt
  • Running gulp
  • Running jspm
  • Running Karma
  • Running Webpack
  • Running bun
  • Optional Configuration
  • Working directory
  • Installation Directory
  • Proxy settings
  • Environment variables
  • Ignoring Failure
  • Skipping Execution
• Eclipse M2E support
• Helper scripts
• To build this project:
• Issues, Contributing
• License

Recommendation: Try to run all your tasks via npm scripts instead of running bower, grunt, gulp etc. directly.

Installing node and npm

The versions of Node and npm are downloaded from https://nodejs.org/dist, extracted and put into a node folder created in your installation directory . Node/npm will only be "installed" locally to your project. It will not be installed globally on the whole system (and it will not interfere with any Node/npm installations already present).

<plugin>
    ...
    <executions>
        <execution>

            <id>install node and npm</id>
            <goals>
                <goal>install-node-and-npm</goal>
            </goals>

            <phase>generate-resources</phase>
        </execution>
    </executions>
    <configuration>
        <nodeVersion>v24.12.0</nodeVersion>


        <npmVersion>11.6.2</npmVersion>


        <downloadRoot>http://myproxy.example.org/nodejs/</downloadRoot>
    </configuration>
</plugin>

You can also specify separate download roots for npm and node as they are stored in separate repos. In case the root configured requires authentication, you can specify a server ID from your maven settings file:

<plugin>
    ...
    <configuration>

        <nodeDownloadRoot>http://myproxy.example.org/nodejs/</nodeDownloadRoot>

        <serverId>server001</serverId>

        <npmDownloadRoot>https://myproxy.example.org/npm/</npmDownloadRoot>
    </configuration>
</plugin>

You can use Nexus repository Manager to proxy npm registries. See https://help.sonatype.com/display/NXRM3/Npm+Registry

Notice: Remember to gitignore the node folder, unless you actually want to commit it.

Installing node and yarn

Instead of using Node with npm you can alternatively choose to install Node with Yarn as the package manager.

The versions of Node and Yarn are downloaded from https://nodejs.org/dist for Node and from the Github releases for Yarn, extracted and put into a node folder created in your installation directory. Node/Yarn will only be "installed" locally to your project. It will not be installed globally on the whole system (and it will not interfere with any Node/Yarn installations already present).

If your project is using Yarn Berry (2.x or above), the Yarn version is handled per project but a Yarn 1.x install is still needed as a "bootstrap". The plugin will try to detect .yarnrc.yml file in the current Maven project/module folder, at the root of the multi-module project if relevant, and in the folder from which the mvn command was run. If detected, the plugin will assume your project is using Yarn Berry. It will install the 1.x Yarn version you specify with yarnVersion as bootstrap, then hand over to your project-specific version.

Have a look at the example POM to see how it should be set up with Yarn: https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/yarn-integration/pom.xml

<plugin>
    ...
    <execution>

        <id>install node and yarn</id>
        <goals>
            <goal>install-node-and-yarn</goal>
        </goals>

        <phase>generate-resources</phase>
    </execution>
    <configuration>
        <nodeVersion>v24.12.0</nodeVersion>
        <yarnVersion>v0.16.1</yarnVersion>


        <nodeDownloadRoot>http://myproxy.example.org/nodejs/</nodeDownloadRoot>

        <yarnDownloadRoot>http://myproxy.example.org/yarn/</yarnDownloadRoot>
    </configuration>
</plugin>

Installing node and corepack

You can choose to let corepack manage the package manager version in use. Node is downloaded from https://nodejs.org/dist, and corepack either comes provided with Node, or will currently be downloaded from https://repository.npmjs.org, extracted and put into a node folder created in your installation directory.

Node/corepack and any package managers will only be "installed" locally to your project. It will not be installed globally on the whole system (and it will not interfere with any Node/corepack installations already present).

Have a look at the example POM to see how it should be set up with corepack: https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/corepack-provided-integration/pom.xml or https://github.com/eirslett/frontend-maven-plugin/blob/master/frontend-maven-plugin/src/it/corepack-integration/pom.xml if you need to override the version of corepack in use.

<plugin>
    ...
    <execution>

        <id>install-node-and-corepack</id>
        <goals>
            <goal>install-node-and-corepack</goal>
        </goals>

        <phase>generate-resources</phase>
    </execution>
    <configuration>
        <nodeVersion>v24.12.0</nodeVersion>


        <corepackVersion>v0.25.2</corepackVersion>


        <nodeDownloadRoot>http://myproxy.example.org/nodejs/</nodeDownloadRoot>

        <corepackDownloadRoot>http://myproxy.example.org/corepack/</corepackDownloadRoot>
    </configuration>
</plugin>

Installing bun

The version Bun is downloaded from https://github.com/oven-sh/bun/releases/download/, extracted and put into a bun folder created in your installation directory . Bun will only be "installed" locally to your project. It will not be installed globally on the whole system (and it will not interfere with any Bun installations already present).

<plugin>
    ...
    <executions>
        <execution>

            <id>install bun</id>
            <goals>
                <goal>install-bun</goal>
            </goals>

            <phase>generate-resources</phase>
        </execution>
    </executions>
    <configuration>

        <bunVersion>v1.1.34</bunVersion>
    </configuration>
</plugin>

Running npm

All node packaged modules will be installed in the node_modules folder in your working directory. By default, colors will be shown in the log.

<execution>
    <id>npm install</id>
    <goals>
        <goal>npm</goal>
    </goals>


    <phase>generate-resources</phase>

    <configuration>

        <arguments>install</arguments>
    </configuration>
</execution>

Notice: Remember to gitignore the node_modules folder, unless you actually want to commit it. Npm packages will always be installed in node_modules next to your package.json, which is default npm behavior.

npx

You can also use npx command, enabling you to execute the CLI of installed packages without a run-script, or even packages that aren't installed at all.

<execution>
    <id>say hello</id>
    <goals>
        <goal>npx</goal>
    </goals>

    <phase>generate-resources</phase>

    <configuration>
        <arguments>cowsay hello</arguments>
    </configuration>
</execution>

Running yarn

As with npm above, all node packaged modules will be installed in the node_modules folder in your working directory.

<execution>
    <id>yarn install</id>
    <goals>
        <goal>yarn</goal>
    </goals>
    <configuration>

        <arguments>install</arguments>
    </configuration>
</execution>

Yarn with Private Registry

NOTE: if you have a private npm