Lombiq Node.js Extensions

About

This project provides several MSBuild-integrated frontend asset pipelines - for building and linting SCSS, JS, Markdown and other arbitrary files. It uses static configuration from your package.json with sensible defaults to free you from managing NPM packages and scripts yourself.

It makes use of our NPM MSBuild Targets project, which can make NPM package management in your project a lot easier, too.

If you're interested in an overview of the rationale behind this project, and a glimpse at its inner workings, see our blog post. Check out a demo video here, and the Orchard Harvest 2023 conference talk about automated QA in Orchard Core here.

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

• The new Lombiq website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Ik wil een taart website (see case study).
• The new Show Orchard website when migrating it from Orchard 1 DotNest to DotNest Core (see case study).
• The new Git-hg Mirror website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Hastlayer website when migrating it from Orchard 1 to Orchard Core (see case study).
• The new Orchard Dojo website when migrating it from Orchard 1 to Orchard Core (see case study).
• It also makes DotNest, the Orchard Core SaaS better.

Do you want to quickly try out this project and see it in action? Check it out, together with its accompanying samples projects, in our Open-Source Orchard Core Extensions full Orchard Core solution. You will find our other useful Orchard Core-related open-source projects there, too.

Prerequisites

1. To use this project, you will most of all need Node.js 18 or newer. We suggest installing the current LTS version which is higher than this minimum.
2. Please follow our recommended setup guides for Windows or Linux, as applicable.

PNPM 8 (for package management and script execution) is automatically enabled via corepack in the EnablePnpm MSBuild target, so you don't have to install it separately. Since PNPM 8 dropped support for Node.js 14 or older, those node versions won't work.

Installation

This project can be consumed as a git submodule or as a NuGet package.

As a Git submodule

In the case of using Lombiq.NodeJs.Extensions as a git submodule, it is recommended to put it into a folder named Lombiq.NodeJs.Extensions under the src/Utilities folder, but you are free to use a different location (in that case you'll need to adjust the paths in the linter configuration files, see the docs on ESLint and Stylelint configuration). You need to add Lombiq.Npm.Targets to the same folder, though.

Then, add a project reference to Lombiq.NodeJs.Extensions/Lombiq.NodeJs.Extensions.csproj and the following Import statements to your project file:

<!-- At the top: -->
<Import Project="..\..\Utilities\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions.props" />

<!-- At the bottom: -->
<Import Project="..\..\Utilities\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions\Lombiq.NodeJs.Extensions.targets" />

ℹ In case you've placed the submodule in a different location or your consuming project is nested deeper, adjust the paths as necessary.

As a NuGet package

When adding Lombiq.NodeJs.Extensions as a NuGet package, no further steps are necessary.

ℹ Mind the following restrictions before choosing the NuGet package:

• No global ESLint configuration
• No global Stylelint configuration

Usage

Integration with MSBuild

The Lombiq Node.js Extensions project tightly integrates with MSBuild and executes linting, compilation and minification tasks as part of the project's regular build process. All generated assets will be properly embedded in the project's assembly.

In case of warnings or errors during the execution of the different pipelines, respective MSBuild warnings and errors will be generated and surfaced. To increase the log verbosity, set <NxVerbosity> to a higher importance value than the default Low in your project file.

Configuration

This project contains some default configuration which can be customized to suit your needs. Your configuration needs to be placed in your project's package.json file like so:

"nodejsExtensions": {
  "assetsToCopy": [ { }, { } ],
  "scripts": { },
  "styles": { },
}

Refer to the respective pipelines for details.

Available pipelines

Here's an overview of the asset pipelines this project makes available:

• Asset Copying
• JavaScript
• Markdown
• Styles

Please check out our dedicated Samples project to see the integration in action. The NuGet Samples project shows how to use Lombiq.NodeJs.Extensions as a NuGet package.

How to trigger pipelines on demand

Many of the pipeline steps can be run from the Visual Studio Task Runner Explorer to avoid building the whole project. Follow these steps to set this up:

1. Build your project once to bootstrap the integration of Lombiq Node.js Extensions into your project.

2. Ensure any or all of the following scripts entries are part of your package.json:

   "scripts": {
     "build":   "npm explore nodejs-extensions -- pnpm build",
     "compile": "npm explore nodejs-extensions -- pnpm compile",
     "lint":    "npm explore nodejs-extensions -- pnpm lint",
     "clean":   "npm explore nodejs-extensions -- pnpm clean",
     "watch":   "npm explore nodejs-extensions -- pnpm watch"
   }

3. Install the NPM Task Runner extension.

4. Open the Task Runner Explorer window and select your project. You should now see the above scripts under the Custom node.

5. Execute any of the available scripts by double-clicking.

6. You will now be able to inspect any errors and linter violations directly in the attached console.

Scripts details

The build script is a wrapper for the build:styles, build:scripts and build:assets scripts, which each constitute their own pipeline, and which are executed in parallel. This is the script that's used during the regular project build.

The compile script is a wrapper for the compile:styles, compile:scripts and compile:assets scripts, which are also executed in parallel. This is the script that's used during NuGet packaging.

The lint script calls respective linting scripts for SCSS, JavaScript and Markdown files, which are part of their respective pipelines and are executed in parallel.

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.