Table of Contents

Getting started

Install the CLI, create an app, and run it with nite watch. About five minutes, most of it the first package download.

Requirements

  • The .NET 10 SDK. Check with dotnet --version.
  • Linux, macOS or Windows on x64 or Arm64. NiteFx downloads the matching esbuild (and, if you use Sass, Dart Sass) binary for your platform.
  • Network access to the npm registry the first time: NiteFx downloads esbuild and your packages, then caches them per user. After that, startup reuses the cache and the lockfile. A private registry or mirror works too; see Private registries.

You do not need Node.js, npm, or any global JavaScript tooling.

Install NiteFx

NiteFx is three packages on nuget.org: Nite, the library your web project references; Nite.Cli, the nite command-line tool; and Nite.Templates, optional dotnet new templates.

How release binaries are signed, and who approves it, is in the Code signing policy.

dotnet tool install --global Nite.Cli
nite version

New projects reference the Nite package from nuget.org with no further setup. To update later, run nite update-self.

Create an app

nite init creates a project in a new folder (or the current one) and installs its packages.

nite init my-app
cd my-app

my-app/
  my-app.csproj
  Program.cs              AddNite, UseNite, an /api/hello endpoint, MapNiteSpa
  nite.json               packages and settings for the client
  nite.lock.json          resolved versions (commit it)
  Client/
    index.html            the entry page
    main.tsx              createRoot(...).render(<App />)
    App.tsx               calls /api/hello and re-fetches on C# changes
    styles.css
    tsconfig.json
  node_modules/           installed packages (ignored by git)
Tip

Set your preferred template once with nite config set init.template islands.

With dotnet new

The same templates come as a dotnet new template pack, which also lists them in Visual Studio's and Rider's new-project dialogs:

dotnet new install Nite.Templates
dotnet new nite-spa -o my-app          # Single-page app
dotnet new nite-islands -o my-site     # Razor Pages with islands

nite init and dotnet new write the same files. The difference: nite init installs the packages in nite.json straight away, while with dotnet new the first nite watch (or nite install) does. You still need the nite tool to run and publish the app. Update the templates with dotnet new update.

Run it

nite watch

nite watch runs dotnet watch with NiteFx handling the browser. The first start downloads esbuild and pre-bundles React (a few seconds); after that it starts in about as long as the app takes to build. dotnet watch opens your browser at the URL in Properties/launchSettings.json.

Now try the loop:

  1. Edit Client/App.tsx. Change the heading and save. The page updates in place in about 150 ms. Click the button a few times first: the count survives the edit.
  2. Edit Program.cs. Change the message /api/hello returns and save. Hot reload applies it in the running app and the page re-fetches, still without a reload.
  3. Break something. Delete a closing brace in App.tsx. An overlay shows the error with its location; fixing it clears the overlay.
  4. Add an endpoint. Add a new app.MapGet(...) line to Program.cs. That needs a restart, so nite watch restarts the app and the page reloads once it is back (about 10 seconds).

For the Razor template, run nite watch --browser-refresh instead, so dotnet watch reloads the page when a .cshtml file changes. See Hot reload and nite watch.

Add a package

nite add react-router          # a runtime dependency
nite add -D @types/node        # a dev dependency (types, tooling)

nite add updates nite.json, resolves versions into nite.lock.json and installs into node_modules. If the app is running, the dev server notices the change, pre-bundles the new package and reloads the page. See Packages.

Publish

dotnet publish -c Release

Release builds run nite build, which writes minified, content-hashed bundles to wwwroot/_nite; the publish output serves them precompressed through MapStaticAssets. Nothing in the published app needs Node, esbuild or node_modules. See Production builds and deployment.

Already have a Vite app?

nite init my-app --from ../my-vite-app --dry-run   # see the plan
nite init my-app --from ../my-vite-app             # do it; the source is not changed

See Importing a project.

Working with an AI coding agent

NiteFx is newer than the training data of most AI models, and it looks enough like Vite that an agent working from memory will reach for npm install and vite.config.ts. Two things help:

  • New projects include an AGENTS.md, which most coding agents (Codex, Cursor, GitHub Copilot, Claude Code and others) read on their own. It lists the commands, the project layout and the Vite habits that do not apply. Edit it as the project grows; it is yours. If you also keep a CLAUDE.md, Claude Code reads that instead, so put @AGENTS.md at its top to include both.
  • The docs are published for agents to read: /llms.txt is an index, /llms-full.txt is every page in one file, and every page is also available as Markdown at its URL with .md instead of .html. Point an agent at them before asking it to work on a NiteFx project.

Next steps

Edit this page