Lombiq NPM MSBuild Targets

About

Provides automatic NPM package installation and a custom NPM command execution before building a .NET project. This way it is possible for example to manage assets (e.g. .scss files or images) in a folder that will be automatically compiled into the wwwroot folder on build, which then can be excluded from the version control system. These operations are optimized by running them only if the corresponding files have been changed.

We at Lombiq also used this utility for the following projects:

• The new City of Santa Monica website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Smithsonian Folkways Recordings website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Lombiq website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new client portal for WTW (see case study).

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

Also see our Node.js Extensions project, which contains complete asset pipelines built on top of this project.

Do you want to quickly try out this project and see it in action? Check it out in our Open-Source Orchard Core Extensions full Orchard Core solution and also see our other useful Orchard Core-related open-source projects!

How to use

Install the NuGet package, or if you use the project from a submodule, add the following lines to the csproj file where the package.json file is. Make sure that the paths are pointing to the Lombiq.Npm.Targets.props and Lombiq.Npm.Targets.targets files of this project.

<Import Project="path\to\Lombiq.Npm.Targets\Lombiq.Npm.Targets.props" />
<Import Project="path\to\Lombiq.Npm.Targets\Lombiq.Npm.Targets.targets" />

The npm install (or pnpm install, see below) command will be executed but only if the package.json file exists and has been changed since the last build (i.e. you un/installed or up/downgraded packages). Note that if you update NPM then the package.json and package-lock.json files can change on npm install; currently, there's no way to prevent this (npm ci is much slower).

An npm run dotnet-prebuild --if-present script will be also executed during the build process, which can be utilized to run a custom task. This will only happen if the files defined in NpmDotnetPrebuildWatchedFiles have changed (to achieve incremental build). By default, these files contain package.json, Assets/**/*.*, Scripts/**/*.*, and Styles/**/*.*. If you want to adjust this list to cover your custom folders and files, override the given MSBuild item in your project file as follows:

<ItemGroup>
  <NpmDotnetPrebuildWatchedFiles Include="package.json;CustomFolder/**/*.*" />
</ItemGroup>

If you want to utilize this, then add a dotnet-prebuild script to the package.json file as follows (npm run build is just an example command):

{
  "private": true,
  "scripts": {
    "dotnet-prebuild": "npm run build"
  }
}

Similarly, you can execute npm run dotnet-postclean --if-present via the dotnet-postclean script to clean up anything after an MSBuild Clean, for example:

{
  "scripts": {
    "dotnet-postclean": "npm run clean"
  }
}

Using PNPM

PNPM is a faster and more efficient package manager. If it's available in the current shell, NPM Targets will use pnpm instead of npm to restore packages.

For details on setting up PNPM, refer to these prerequisites.

If you want to keep compatibility with NPM, then you have to maintain both pnpm-lock.yaml and package-lock.json files, since PNPM uses its own package lock file.

Contributing and support

Bug reports, feature requests, comments, questions, code contributions and love letters are warmly welcome. You can send them to us via GitHub issues and pull requests. Please adhere to our open-source guidelines while doing so.

This project is developed by Lombiq Technologies. Commercial-grade support is available through Lombiq.