PlayNicely.NpmNpx 1.0.3.64-prerelease-20240105-121407

npm & npx

NuGet package to inject npm and npx tooling into your project.

The purpose of this project is to support node_modules that handle build time tasks in web/js projects, such as the awesome tailwindcss, sass, or TypeScript (without having to install these modules globally, although Node.js does need to be installed).

Installation

Simply install this package into your project like any other NuGet dependency.

Install-Package PlayNicely.NpmNpx

Getting Started

The default installation creates a package.json (if there isn't one already) in the project root directory (the owning project of this dependency). That @(NpmProject) is the one included in the build.

This project on its own doesn't do anything particularly interesting. The easiest way to utilize it is to use one of its leaf projects for sass or tailwindcss. But if you need to add a npm package for something else, you can and it allows you to call it during the dotnet build process.

An example with tailwindcss

Let's say you want to use tailwindcss in you web project. From a shell:

1. Install tailwindcss as a dev dependency, and create a base tailwind.config.js.

   npm install -D tailwindcss
   npx tailwindcss init
   

2. Configure your tailwind environment.
3. Add a tailwindcss build <Target> to your project, e.g. *.csproj, file. Notice that the target (below) depends on npm-install and BeforeBuild. It depends on the node modules being installed and the BeforeBuild processing, before generating the tailwind site.css file.

   <Target Name="tailwind-build" DependsOnTargets="npm-install;BeforeBuild">
     <Exec Command="npx tailwind build -i ./srcroot/css/site.css -o ./wwwroot/css/site.css" />
     <ItemGroup>
   
       <Content Include="wwwroot/css/tw.css" Exclude="@(Content)" />
     </ItemGroup>
   </Target>
   

Configuration

The package includes two MSBuild Project files, that are <Import>ed into your project:

• PlayNicely.NpmNpx.props - contains the most common default properties for node projects, package.json file in the root of the project.
  • NpmRootDirectory - The root of the node project, defaults to the project that is installing this dependency.
  • NpmProject - A default (MSBuild) item NpmProject, this is the package.json file in the root of the dependent project.
• PlayNicely.NpmNpx.targets - A basic set of (MSBuild) targets:
  • npm-version and npx-version - to check that npm/npx are installed.
  • npm-init - Runs npm init -y for any @(NpmProject) items that have not been initialized with a package.json.
  • npm-install - Runs npm install for any @(NpmProject) items, to ensure node dependencies have been installed locally.

Other properties that effect build:

• <NpxRequired> - set this to false if your build does not require the npx tool. If this property is false, then the build will not fail if npx is not detected.

Multiple NpmProject's

The most common scenario is for a web project to contain a single package.json file and node_nodules directory. You can have multiple projects by defining them in you MSBuild project file (csproj). Each node project must be in it's own directory.

It is recommended that you create your package.json files manually and add any dependencies using npm init and npm install, if you don't, the build targets will call npm init -y for each NpmProject that is defined where the package.json does not exist.

npm init -y for missing package.json files.

If an NpmProject is defined but the package.json has not been created, the build targets will initialize those directories using npm init -y defaults. This creates an empty node project with no dependencies (unless the project directory already contains a node_modules directory). This is a convience for the build, but you will still need to add your own npm dependencies using npm install.

Roadmap

Items on (or not) the roadmap.

More complete documentation

Provide more complete documentation of this product and it's features.

We may do this if the number of downloads increases.

Requiring a version of npm or npx

It may be desirable to require a certain version of the products so that we can rely on a particular feature only in a certain version.

Yep, we might do this.

Better handling of existing node_modules directory and npm init -y

When running npm init -y, if the directory contains an existing node_modules directory, all of the packages in that directory get added to the package.json as dependencies. This is probably not optimal and should be handled in a (TBC) different way.

We might do something about this if we can think of a sensible approach.

Install Node.js if it is not detected on the target system

No we won't be doing this.

Roadmap Internal

Test Projects

Create some test projects to ensure developed features act as intended.

• Basic install
  • Does it run npm init?
  • Does it install dependencies
• Multiple NpmProject items

CI/CD

Ideally build the package files as beta until they are released to production. Publish to NuGet.org feed.

Stages

What might the CI/CD pipeline stages look like?

For main branch

• Prepare
• Package
• Test
• Publish
  • Start (Manual)
  • Package (prod version)
  • Publish
  • Release
  • Version????

Prepare

Build the docker image used as the base for the rest of the process.

Package

Build the project using dotnet build -c Release /p:PreReleaseVersion=true, this generates the /obj/ directory and files (for the production build) and the prerelease *.nupkg file.

Artefacts are

• **/obj/**/* of the code projects
• Output/$(Configuration)/**/NuGet/*.nupkg

Test

Test the nupkg file by installing it into a bunch of test projects, already set up in the repository and making sure that they build as expected.

Publish

Publish the nupkg file to the nuget.org repository.

Package

Convert the

If the merge_request is on the main branch publish a beta. How do we have a downstream prod nupkg?