PlayNicely.NpmNpx 1.3.4-beta-322

Play Nicely - npm & npx

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

The purpose of this project is to support npm packages 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).

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. PlayNicely.Sass. But if you need to add a npm package for something else, you can, and it allows you to execute it during the dotnet build process.

Getting Started

It is recommended that you initialize your Node project and install any dependencies, then install this package.

npm init
npm install --save-dev my-cool-dev-dependency

Once your npm dependencies are installed, install this package to your .NET project.

Install-Package PlayNicely.Sass

ℹ️ Should work by default
We recommend the above process, however, if you just install this package in your .NET project, the default build process will check to see if package.json exists in the root directory. If the file does not exist, the build will run npm init ‑y to create it.

The package.json file is included in the build as a NpmProject MSBuild item and is used to decide what, if any npm commands need to be ran. This includes npm init ‑y and npm install.

An example with tailwindcss

Let's say you want to use tailwindcss in you web project.

From a shell:

1. Initialize the node project.

   npm init
   

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

   npm install -D tailwindcss
   npx tailwindcss init
   

3. Install this package.

   Install-Package PlayNicely.NpmNpx
   

4. Configure your tailwind environment.

5. Add a tailwindcss build Target to your .NET project file. Notice that the target (below) depends on npm‑install and runs after target BeforeBuild. It depends on any npm packages 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 imported into your project:

• PlayNicely.NpmNpx.props
  Contains the most common default properties, and items, for node projects.
  • NpmRootDirectory
    A property which is the root of the node project, defaults to the project that is installing this dependency.
  • NpmProject
    A default item, this is the package.json file in the root of the dependent project.
• PlayNicely.NpmNpx.targets
  A basic set of MSBuild Target definitions:
  • npm‑version and npx‑version
    To check that the npm and npx executables, 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 succeed, even if npx is not detected. This property is not set by default, which is equivalent to true.
• NpmAutoInit
  Set this to false if you want to manually initialize your node project with npm init. This property is not set by default, which is equivalent to true.

To change these defaults, simply add them to a PropertyGroup in your project file.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    
    <NpxRequired>false</NpxRequired>
    
    <NpmAutoInit>false</NpmAutoInit>
  </PropertyGroup>

  
</Project>

Multiple Node Projects

The most common scenario is for a web project to contain a single node project, a package.json file. And for that node project to be at the root of the MSBuild project. You can have multiple node projects, by defining them in your MSBuild project, but each package.json needs to be in a separate directory.

<Project Sdk="Microsoft.NET.Sdk">
  

  <ItemGroup>
    <NpmProject Include="path/to/package.json" />
  </ItemGroup>

  
</Project>

npm init -y for missing package.json files

If a NpmProject is defined but the package.json does not exist, the build targets will initialize those projects, using npm init ‑y, by default. This creates an empty node project with no dependencies. This is a convience so the build succeeds by default. You will still need to add your own npm dependencies, using npm install, to do anything useful.

⚠️ Default npm init ‑y behavior
If the project directory already contains a node_modules directory, the npm init ‑y command will add all packages in the node_modules directory as dependencies in the created package.json.

It is recommended that you create your package.json files manually, using npm init, and add any dependencies using npm install.