Delivering a Node.js asset pipeline as a NuGet package
How long does it take you to set up a Node.js-based frontend asset pipeline? That lints and compiles your SCSS, JavaScript, Markdown? That makes code style inconsistencies a tale of the past? In .NET?
With Lombiq Node.js Extensions, it'll take you under a minute.
In this post, we will provide an overview of what we’ve squeezed into Lombiq Node.js Extensions, how we packaged it for NuGet, why we ditched Gulp, and some gems on MSBuild integration. If you want to see a demo of Lombiq Node.js Extensions in action, check out our recent This week in Orchard post.
Web Development in 2023 needs Node.js
Even in the .NET world, Node.js has become a first-class citizen for all matters frontend. Grunt, Gulp, Babel, Webpack – all Node.js-based tools – have conquered the frontend landscape. Orchard Core uses Gulp to build its modules’ assets. At Lombiq, we used to use Gulp to build our assets. But it's...
Time to say goodbye
While Gulp provides a great development experience, there are downsides:
-
Gulp wrappers around NPM packages were not always available or up to date. Sometimes, they caused unexpected errors after updates.
-
Lack of support for Node.js 14 and above became an issue.
-
Plain NPM and Node.js scripts can do the same work as a Gulp script.
-
One less moving part in our tooling ecosystem means less friction.
Based on experience with our Gulp Extensions project, we've built a tool that eliminates its weaknesses.
Building a reusable frontend asset pipeline on top of Node.js
Why? - So you can simply plug it into your projects. Like we do!
How? - Read on!
What? - Here's an excerpt of what Lombiq Node.js Extensions does:
-
lints SCSS, compiles, autoprefixes and minifies it, generating source maps on the way
-
lints JS, minifies it, generates source maps
-
lints Markdown
-
provides sensible defaults for Orchard-based web development, i.e. needs no manual configuration in the default scenario!
-
can copy assets to a webroot folder, like image files and frontend libraries
-
is usable from a NuGet package
-
integrates tightly with MSBuild
-
adds generated assets to the project's assembly
-
allows to keep generated assets excluded from version control
-
uses PNPM to efficiently install packages and execute scripts (if you don't know it, PNPM is a Node.js package manager with a lot of advantage over NPM)
The important pieces
Let's look at some of the magic sauce that makes all this possible!
MSBuild takes care of the build
We use our Lombiq NPM MSBuild Targets project to hook the necessary Node.js work into the MSBuild build pipeline. All the asset manipulation happens before a project's Compile target executes. That allows us to generate frontend assets and embed them into the project's assembly as part of the .NET build.
There was a challenge here, though: Files that are generated during the build need to be added manually to the EmbeddedResource item group, else they won't be embedded in the DLL. Here's the relevant piece from the AddGeneratedFilesToEmbeddedResourceList target in Lombiq.NodeJs.Extensions.targets:
<ItemGroup>
<EmbeddedResource Include="@(NodeJsExtensionsTargetFiles)" WithCulture="false" Type="Non-Resx" />
</ItemGroup>
Node.js complexities are handled under the hood
Setting up Stylelint, ESLint, Markdownlint and other NPM packages can be time-consuming and complex. Lombiq Node.js Extensions has it all set up and configured out of the box!
When your project integrates Lombiq Node.js Extensions and you accept the defaults, you are done. Installation and execution of the SCSS and JavaScript pipelines happen automagically. You even get live ESLint support in Visual Studio with our preconfigured settings! And if you need, you are free to extend them.
Packing it up with NuGet
Configuring NuGet packaging can be tedious, but here's our successful configuration. Most of all, we include all the files that are necessary to later install this project as an NPM package in any consuming project. As the documentation states:
A package [can be] a folder containing a program described by a package.json file.
Using Lombiq Node.js Extensions from a NuGet package is the simplest way to get started. When using it from a Git submodule, you will need to edit your project file.
Outsource your frontend asset pipelines
Are you still writing CSS, because you don't want to invest in setting up the necessary tooling to compile SCSS as part of your build?
Do you still argue over your JavaScript files' code styling?
Is inconsistent Markdown formatting plaguing you?
Let Lombiq Node.js Extensions handle all that for you. Get the NuGet package today!
Should you need any further help, file an issue or contact us for commercial-grade support.