PlayNicely.NpmNpx 1.3.4-beta-297

Play Nicely - 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 settings create, during build, a package.json if there isn't one already, using npm init -y. The project root directory (the owning project of this dependency) is where the package.json file is created. That package.json is added as an @(NpmProject) MSBuild item and is available as part of the build process.

This project on its own doesn't do anything particularly interesting. The easiest way to utilize it is to use one of its dependent projects, e.g. sass. 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 (csproj) project file. Notice that the target (below) depends on npm-install and runs AfterTargets BeforeBuild. It depends on any node modules being installed and any BeforeBuild processing, before generating the tailwind site.css file.

   <Target Name="tailwind-build"
           DependsOnTargets="npm-install"
           AfterTargets="BeforeBuild">
     <Exec Command="npx tailwind build -i ./src/site.css -o ./wwwroot/css/site.css" />
     <ItemGroup>
   
       <Content Include="wwwroot/css/site.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 and npx, respectively, are installed and fail the build if they aren't.
  • 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. The default for this property is true.
• <NpmAutoInit> - set this to false if you want to manually initialize your node project, with npm init. The default for this property is true.

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 (csproj) project file. Each node project must be in it's own directory.

npm init -y for missing package.json files.

If a @(NpmProject) is defined but the package.json has not been created, the build targets will initialize those directories using npm init -y by default. 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.

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. This auto init of the package.json file can be disabled by setting the build property <NpmAutoInit>false</NpmAutoInit>.