SimpleW.Helper.NpmTooling
26.2.0-alpha.20261122-2402
dotnet add package SimpleW.Helper.NpmTooling --version 26.2.0-alpha.20261122-2402
NuGet\Install-Package SimpleW.Helper.NpmTooling -Version 26.2.0-alpha.20261122-2402
<PackageReference Include="SimpleW.Helper.NpmTooling" Version="26.2.0-alpha.20261122-2402" />
<PackageVersion Include="SimpleW.Helper.NpmTooling" Version="26.2.0-alpha.20261122-2402" />
<PackageReference Include="SimpleW.Helper.NpmTooling" />
paket add SimpleW.Helper.NpmTooling --version 26.2.0-alpha.20261122-2402
#r "nuget: SimpleW.Helper.NpmTooling, 26.2.0-alpha.20261122-2402"
#:package SimpleW.Helper.NpmTooling@26.2.0-alpha.20261122-2402
#addin nuget:?package=SimpleW.Helper.NpmTooling&version=26.2.0-alpha.20261122-2402&prerelease
#tool nuget:?package=SimpleW.Helper.NpmTooling&version=26.2.0-alpha.20261122-2402&prerelease
SimpleW.Helper.NpmTooling
A SimpleW add-on for managing an npm frontend during development and serving its compiled files in production. The browser calls the SimpleW API directly. No API proxy or JavaScript integration plugin is required.
Standalone usage
using System.Net;
using SimpleW;
using SimpleW.Helper.NpmTooling;
var server = new SimpleWServer(IPAddress.Loopback, 8080);
server.MapGet("/api/hello", () => new { message = "Hello" });
server.UseNpmToolingModule();
await server.RunAsync();
In the server's .csproj, inside <Project>:
<PropertyGroup>
<SimpleWNpmSourcePath>C:\projects\my-app\client</SimpleWNpmSourcePath>
<SimpleWNpmDistPath>$(SimpleWNpmSourcePath)/dist</SimpleWNpmDistPath>
<SimpleWNpmPublishPath>wwwroot</SimpleWNpmPublishPath>
<SimpleWNpmApiBaseUrl>/api</SimpleWNpmApiBaseUrl>
<SimpleWNpmBuildClient>true</SimpleWNpmBuildClient>
</PropertyGroup>
Set SimpleWNpmSourcePath to the full path of the folder containing package.json. The NuGet package imports its targets automatically and embeds the shared settings at each build. Rebuild after changing them; the module reads them once when installed. No settings file is needed.
Use this setup for development and deployment. options.Environment defaults to NpmEnvironment.AutoDetect: regular builds run npm, and published applications serve compiled files. To force a mode, use server.UseNpmToolingModule(options => options.Environment = NpmEnvironment.Development) or NpmEnvironment.Production. Register the module once, before starting the server.
Regular builds write SimpleW.Published=false; dotnet publish writes true, regardless of Debug/Release. The marker stays with the binary if copied or launched directly from bin. A subsequent regular build restores false. Automatic publication detection is supported for the dotnet publish CLI; IDE publishing has not been verified.
Development prerequisites: Node >= 22.12 and npm, available on the IDE's PATH. The module targets .NET 8, 9 and 10 and SimpleW 26.2.x. It supports frontends that produce static files; it does not host a Node SSR server in production.
API address
The module passes the same API address to the npm process through two environment variables: SIMPLEW_API_URL for any frontend tool and VITE_SIMPLEW_API_URL for Vite. Configure their shared value with SimpleWNpmApiBaseUrl in the .csproj. It accepts an API path such as /api (the default) or a complete HTTP(S) URL such as https://backend.example/services.
In development, a path is resolved against the active SimpleW listener; wildcard bind addresses become loopback addresses. During publication, the path is passed unchanged to the frontend build, so /api uses the deployed application's origin. A complete HTTP(S) URL is always used unchanged and is required for a Unix socket listener. Credentials, whitespace, queries and fragments are not accepted.
The path part also determines the development CORS scope and the API namespace excluded from production SPA fallback. For example, https://backend.example/services reserves /services and its descendants. A root address (/ or a URL with no path) has no dedicated API namespace to exclude from SPA fallback; explicit backend routes still take precedence. This option does not create or rewrite routes. If the URL targets another server, that server must allow frontend requests through its own CORS configuration.
In a SPA using Vite:
const apiBaseUrl = import.meta.env.VITE_SIMPLEW_API_URL;
if (!apiBaseUrl) throw new Error('VITE_SIMPLEW_API_URL is missing.');
const response = await fetch(`${apiBaseUrl}/hello`);
Vite exposes VITE_SIMPLEW_API_URL to client code natively. Other frontend tools can read process.env.SIMPLEW_API_URL in their Node.js configuration and expose it to browser code using their own mechanism. Both variables are passed only to the child process, without changing the system environment or writing a configuration file; the module does not require a plugin.
The frontend chooses its own host and port. The module discovers the actual local HTTP(S) URL from the development script's stdout or stderr, verifies that it responds, then opens that URL and enables CORS for its origin. No frontend URL is configured in C# and no frontend configuration file is rewritten. A different port chosen by the frontend is detected automatically.
Startup announcements such as Local: http://localhost:5173/ (Vite's default output), Loopback: ..., or Listening on http://127.0.0.1:3000/ are recognized, including terminal colors, IPv6 and application base paths. Only loopback URLs are accepted; wildcard bind addresses 0.0.0.0 and [::] are converted to their loopback counterparts. Arbitrary URLs in npm command echoes, documentation links and network announcements are ignored. The development script must keep its address announcement enabled; custom/silent log formats are not universally discoverable. HTTPS certificates must be trusted by the machine running the backend.
Keep your existing frontend configuration and plugins. If the frontend also opens a browser, disable that feature there (for example server.open: false in Vite) to let NpmTooling open it once. Do not add an /api proxy for this integration.
Project properties
| Property | Default | Purpose |
|---|---|---|
SimpleWNpmSourcePath |
../client |
Folder containing package.json, absolute or relative to the .csproj. |
SimpleWNpmDistPath |
$(SimpleWNpmSourcePath)/dist |
Frontend build output, absolute or relative to the .csproj; used only during publication. |
SimpleWNpmPublishPath |
wwwroot |
Relative frontend subfolder inside the published application. Absolute paths and paths outside that directory are rejected. |
SimpleWNpmApiBaseUrl |
/api |
API path or complete HTTP(S) URL shared by development and publication. |
SimpleWNpmBuildClient |
true |
Run the frontend build during publication; false copies an already built frontend. |
The source path is embedded as an absolute path. The published frontend folder is resolved relative to AppContext.BaseDirectory, so the deployment can be moved as a whole.
C# options
Use the optional UseNpmToolingModule(options => { ... }) callback for these settings:
| Option | Default | Purpose |
|---|---|---|
Environment |
NpmEnvironment.AutoDetect |
Production for a marked published application, otherwise Development. Use NpmEnvironment.Development or NpmEnvironment.Production to force a mode. |
Script |
dev |
npm script to run |
ScriptArguments |
Empty list | Separate arguments after the npm -- separator |
EnableDevelopmentCors |
true |
Install development CORS rules |
InstallDependencies |
true |
Install missing direct dependencies |
OpenBrowser |
true |
Open the frontend once it is available over HTTP |
NpmKeepAlive |
false |
Keep the development frontend alive between backend runs on Windows and Linux |
NpmIdleTimeout |
30 minutes | Positive period before stopping a persistent frontend with no connected backend |
StartupTimeout |
60 seconds | Maximum time to discover the URL and receive HTTP 2xx at its announced path |
InstallTimeout |
10 minutes | Dependency installation time limit |
NodePath / NpmCliPath |
Automatic discovery | Explicit paths for custom installations |
ServerLogger / ClientLogger |
SimpleW.Helper.NpmTooling.Server and .Client loggers | Separate supervision messages and npm output |
Configure options before installing the module; do not change them while it is running. npm stderr output is logged as warnings; process failures are logged by the supervisor.
CORS
In development, the module allows only the discovered frontend origin on the path derived from SimpleWNpmApiBaseUrl, using SimpleW's existing CORS module. No origin is allowed until the frontend is ready; the origin is cleared on shutdown or process exit. Common REST requests and OPTIONS preflights are supported; allowed headers are Content-Type, Authorization. Credentials are disabled, and no wildcard origin is added.
If the application already configures CORS, set EnableDevelopmentCors=false and manage the rules in the application, particularly for cross-origin cookies. The module does not add CORS in production. It neither creates nor moves API routes: those remain defined by the application.
Process supervision
If a direct dependency is missing from the client's node_modules, the module runs npm ci --include=dev when package-lock.json exists, or npm install --include=dev otherwise. Workspaces with packages hoisted to a parent directory can disable automatic installation. Changing a version in the manifest requires updating dependencies separately; detection checks their presence, not their versions.
The module invokes npm-cli.js through Node, without a shell, passing arguments separately. By default, its embedded supervisor monitors a pipe owned by the C# process. Windows also uses a Job Object; Unix uses a dedicated process group. Only processes created by the module are cleaned up, including when the debugger forcibly stops the backend. Processes are never terminated by program name or port number.
In Development, the module launches and owns the frontend, or reconnects to its own persistent supervisor when NpmKeepAlive is enabled. The frontend handles occupied ports according to its own configuration: it can fail or select another port, whose announced URL will be discovered. NpmTooling does not scan ports or attach to an independently launched server. Startup announcements are trusted as coming from the configured script; HTTP availability alone does not prove process ownership.
If startup times out, the supervisor distinguishes between no recognized local URL and announced URLs that never became ready. It logs the failure and stops its owned processes in the default mode. In persistent mode it disconnects, allowing the idle timeout to stop the frontend when no other backend is attached. There is no fallback to a hard-coded port or wildcard CORS origin.
Installations and probes support cancellation. A failure leaves the backend available without automatically restarting the client. After correcting the problem, restart the server. Reloading a listener does not create a second frontend; changing the API origin requires a full restart to refresh the environment variable.
Keep npm running between backend restarts
On Windows and Linux, enable persistent development supervision:
server.UseNpmToolingModule(options => {
options.NpmKeepAlive = true;
options.NpmIdleTimeout = TimeSpan.FromMinutes(30);
});
Stopping the backend disconnects its log subscription, including when the backend process is killed. The independent Node supervisor keeps npm running and starts the idle countdown after the last backend disconnects. Reconnecting cancels that countdown. At expiry, the supervisor terminates the frontend process tree and exits. These options have no effect in Production; NpmKeepAlive defaults to false.
Communication uses a local named pipe on Windows and a Unix socket on Linux, authenticated with a token stored in the user's private runtime directory. A session belongs to one user and one absolute frontend directory, independently of the backend's build output. Concurrent backends can share a compatible session. No additional npm or NuGet package is required.
On reconnection, the frontend URL is checked over HTTP again before enabling CORS and applying OpenBrowser. The supervisor retains up to 1,000 output lines and 1 MiB of encoded history, forwards stdout and stderr to ClientLogger, and marks replayed lines with [history #sequence]. Older discarded lines are reported through ServerLogger; individual lines longer than 8,192 characters are truncated. A slow log consumer is disconnected instead of blocking npm.
The module compares the npm script and arguments, Node/npm paths, injected API environment, idle timeout, package manifests/lock files and supervisor version. If the configuration differs, the backend reports the conflict and disconnects without interrupting the frontend or resetting its idle countdown. Disconnect any other backends and wait for the existing session's idle timeout to expire, then restart the backend with the new configuration. The timeout already running belongs to the existing session; changing the option applies to the next session. Changing a package version still requires updating the installed dependencies separately. Ordinary .NET source changes do not restart npm; frontend source updates remain the development server's responsibility.
No manual stop script or IPC shutdown command is provided. Choose a short NpmIdleTimeout if the frontend should stop soon after the last backend disconnects. The embedded supervisor is an internal runtime implementation detail and is not copied beside the executable as a control tool.
The supervisor uses a Windows Job Object whose lifetime is independent of the backend, or a separate Linux process group (SIGTERM followed by SIGKILL after five seconds if necessary). Windows hosts that prohibit breaking out of their own Job Object cannot provide this persistence: the module reports the launch failure instead of silently falling back to a frontend tied to the backend. If you disable NpmKeepAlive, let the previous persistent frontend's idle timeout expire before starting a nonpersistent instance.
Runtime state lives under %LOCALAPPDATA%/SimpleW/NpmTooling on Windows and ${XDG_DATA_HOME:-$HOME/.local/share}/SimpleW/NpmTooling on Linux. Linux sockets use a private, short directory under /tmp. Stale session metadata is reclaimed on the next startup; it is never used to terminate a process by PID.
Publishing
The NuGet targets embed the shared configuration and publication marker before compilation, independently of GenerateAssemblyInfo. They exclude libraries and IDE design-time builds. Frontend installation, compilation and copying run only when publishing an executable:
dotnet publish -c Release -o ./publish
Publishing installs dependencies, then runs npm run build with both SIMPLEW_API_URL and VITE_SIMPLEW_API_URL set to the same value from SimpleWNpmApiBaseUrl, and NODE_ENV=production. Vite embeds VITE_SIMPLEW_API_URL in the compiled JavaScript. /api uses the domain and port where SimpleW serves the application; an absolute URL can also be used for a separate deployment, with CORS configured in the application.
The dist files are copied to SimpleWNpmPublishPath inside the publish output (publish/wwwroot in this example), as external files even for a single-file publish. An npm failure or a missing dist/index.html fails publication. With SimpleWNpmBuildClient=false, npm is not called: a dist directory already built with the correct API address is required and copied unchanged.
Publication validates the application's metadata without executing it, before running npm. dotnet publish --no-build requires an already published binary with matching source path, publish path and API URL. Otherwise, run dotnet publish without --no-build. Validation also applies with SimpleWNpmBuildClient=false or an explicit C# environment override.
Deploy the whole publish directory and run dotnet MyWebApp.dll. NpmTooling serves the configured frontend folder automatically; no additional StaticFilesModule registration is needed.
Production
The module registers StaticFilesModule on /assets/*, backed by the published assets directory, with directory listing disabled and HTTP caching set to NoCache (revalidate before reuse). Memory caching and streaming retain the static module's defaults. If the directory is absent when the module is installed, asset URLs return 404.
Explicit GET/HEAD routes serve / and /index.html from index.html, plus /favicon.ico and /layers.css from their corresponding root files. Missing optional files return 404. Other public files outside /assets require explicit application routes; the module no longer serves arbitrary files or directory indexes from the frontend root.
The router fallback serves only index.html, for unmatched GET/HEAD navigation requests that explicitly accept text/html and have no extension. Paths under the configured API prefix, /assets and /assets/*, missing URLs with an extension, and other methods return 404 rather than HTML. Existing application routes handle their own responses; a handler returning 404 does not trigger this fallback.
The public directory must contain a safe index.html when the module is installed. Links, junctions, path traversal and hidden paths remain rejected; unsafe asset paths return 403 through the static module's authorization callback. Keep assets immutable while serving them and publish to a clean output directory.
The module occupies the router's root fallback. Avoid another fallback or a global static route that would hide it. Vue routes containing a dot in their final segment do not receive the SPA fallback. Production requires neither Node, npm nor Vite.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. net11.0 is compatible. |
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 26.2.0-alpha.20261122-2402 | 0 | 11/22/2026 |
| 26.2.0-alpha.20261122-2400 | 0 | 11/22/2026 |
| 26.2.0-alpha.20261115-2395 | 80 | 11/15/2026 |
| 26.2.0-alpha.20261113-2366 | 57 | 11/13/2026 |
| 26.2.0-alpha.20261113-2364 | 56 | 11/13/2026 |
| 26.2.0-alpha.20261113-2362 | 53 | 11/13/2026 |
| 26.2.0-alpha.20261112-2357 | 56 | 11/12/2026 |
| 26.1.0-alpha.20261108-2340 | 56 | 11/8/2026 |
| 26.1.0-alpha.20261107-2335 | 50 | 11/7/2026 |
| 26.1.0-alpha.20261106-2333 | 53 | 11/6/2026 |
| 26.1.0-alpha.20261106-2331 | 55 | 11/6/2026 |
| 26.1.0-alpha.20261105-2329 | 56 | 11/5/2026 |
| 26.1.0-alpha.20261105-2324 | 49 | 11/5/2026 |
| 26.1.0-alpha.20261105-2322 | 55 | 11/5/2026 |
| 26.1.0-alpha.20261105-2320 | 51 | 11/5/2026 |
| 26.1.0-alpha.20261101-2306 | 60 | 11/1/2026 |
| 26.1.0-alpha.20261031-2306 | 66 | 11/1/2026 |
