# NiteFx

> NiteFx is TypeScript and React for ASP.NET Core with a Vite-style dev loop and no Node.js toolchain. It compiles client code on request with esbuild, keeps component state across hot updates, installs npm packages with its own C# client, and ships hashed, code-split bundles from `dotnet publish`. It needs the .NET SDK and nothing else.

## Notes for AI coding agents

NiteFx looks like Vite but is not Vite, and habits from Vite and Node projects produce code that
does not work. In a NiteFx project:

- There is no `package.json`, `node`, `npm`, `npx` or `vite.config.*`. Do not create them.
  Packages are listed in `nite.json` and locked in `nite.lock.json`.
- Add packages with `nite add <name>` (`nite add -D <name>` for dev-only ones such as types),
  remove them with `nite remove <name>`, and update them with `nite update`. Never `npm install`.
- Run the app with `nite watch` (or `dotnet watch` / `dotnet run`); there is no separate frontend
  server or dev proxy. `dotnet publish -c Release` runs `nite build` and needs the `nite` tool
  (`dotnet tool install --global Nite.Cli`).
- Client code lives in the client root, `Client/` by default. `Program.cs` calls `AddNite()`,
  `UseNite()` and, for a single-page app, `MapNiteSpa()`; Razor apps use `<island>` tag helpers.
  The API is on the same origin, so there is no CORS to configure.
- Build-time settings come from `import.meta.env.NITE_PUBLIC_*`; `envPrefix` in `nite.json` sets
  other prefixes (projects imported from Vite keep `VITE_`). Per-request values from the server
  come from `NiteOptions.ClientConfig` and `import { config } from "nite:config"`.
- Not supported: `import.meta.glob`, Vite import suffixes (`?raw`, `?url`, `?worker`), Vite,
  Rollup and Babel plugins, and server-side rendering. NiteFx strips types without checking them;
  run `tsc --noEmit` for type errors.
- The project is NiteFx (Nite Framework). Its NuGet packages (`Nite`, `Nite.Cli`, `Nite.Templates`),
  its C# namespace (`Nite`), the `nite` command and its files (`nite.json`, `/_nite`) keep the
  short name.

<!-- Source: https://nitefx.dev/docs/introduction.html -->

# Introduction

NiteFx runs TypeScript and React inside ASP.NET Core the way Vite runs them in Node: compiled on request, with hot updates that keep component state, and a production build that ships hashed, code-split bundles. It needs the .NET SDK and nothing else.

*NiteFx* is short for **Nite Framework**, and *Nite* is pronounced like **night**, not *neat*. (Vite, whose dev loop it borrows, is French for "quick" and is pronounced *veet*.) The NuGet packages (`Nite`, `Nite.Cli`, `Nite.Templates`), the C# namespace and the `nite` command keep the short name.

## The problem

Putting a modern frontend on an ASP.NET Core app usually means running two toolchains side by side:

- a Node.js install, `package.json`, a lockfile and a bundler (Vite, webpack) for the client;
- the .NET SDK, a project file and `dotnet watch` for the server;
- a dev proxy or CORS settings so the two servers can talk, and a build step in CI that stitches the outputs together.

Each half is good at what it does. The seams between them are where the time goes: two terminals, two hot-reload systems that know nothing about each other, a proxy configuration that drifts from production, and a Node version to keep current on every machine and build agent.

## What NiteFx does instead

NiteFx moves the frontend dev server into your ASP.NET Core app. One project, one process, one `dotnet watch`:

- **Edit a React component** and it updates in place, with its state intact (React Fast Refresh).
- **Edit a C# endpoint** and hot reload applies it in the running app; the page gets a `nite:server-update` event and re-fetches, without reloading.
- **Run `dotnet publish`** and the client is built into minified, content-hashed bundles in `wwwroot/_nite`, served precompressed by `MapStaticAssets`.

There is no `node`, `npm`, `package.json` or Vite anywhere. Compilation is done by [esbuild](https://esbuild.github.io), the same Go binary Vite uses for dependency pre-bundling, which NiteFx downloads and drives itself. Packages come from the npm registry through a small npm client written in C#.

## Two ways to use it

**A single-page app.** `Client/index.html` and React (or plain TypeScript), served by `app.MapNiteSpa()` next to your API. The app and the API share an origin, so there is no CORS and no proxy. See [Single-page apps](https://nitefx.dev/docs/guides/single-page-apps.md).

**Islands in Razor pages.** Server-rendered Razor Pages or MVC views with interactive React components exactly where you need them:

```cshtml
<island name="TodoList" props='new { title = "Today", items = Model.Todos }' client="visible">
    @* Server-rendered fallback until the island loads *@
    <ul>@foreach (var t in Model.Todos) { <li>@t.Title</li> }</ul>
</island>
```

See [Islands in Razor Pages](https://nitefx.dev/docs/guides/islands.md).

## How it compares

| | NiteFx | Vite + ASP.NET Core | SPA templates (`SpaProxy`) | LibMan / CDN scripts |
|---|---|---|---|---|
| Node.js required | No | Yes | Yes | No |
| Processes in development | One | Two | Two (proxied) | One |
| TypeScript and JSX | Yes (esbuild) | Yes | Yes | No |
| React Fast Refresh | Yes | Yes | Yes | No |
| C# changes reach the page without a reload | Yes (`nite:server-update`) | No | No | No |
| npm packages | Yes (C# client) | Yes | Yes | A curated subset |
| Sass, Less, Tailwind, PostCSS, CSS modules | Yes | Yes | Yes | No |
| Islands in Razor views | Built in | Manual | No | Manual |
| Vite and Rollup plugins | No | Yes | Yes | No |
| Framework-specific SSR (Next.js, Remix) | No | Via the framework | Via the framework | No |

NiteFx is deliberately smaller than Vite. If your project depends on Vite plugins (Vue single-file components, Svelte, MDX), or on a meta-framework with its own server, keep using those tools. [Limits and non-goals](https://nitefx.dev/docs/limits.md) lists what NiteFx does not do.

## What it is good for

- Internal tools, dashboards and line-of-business apps where the team writes C# and wants a React frontend without adopting the Node ecosystem's operations.
- Razor sites that need a handful of interactive widgets without becoming a single-page app.
- Teams that want one build, one deployment artifact and one dev command.
- Moving an existing Vite or Create React App frontend next to its API, keeping the exact package versions it runs today ([Importing a project](https://nitefx.dev/docs/guides/importing.md)).

## Status

NiteFx is at version **0.8**. The core loop (compilation, Fast Refresh, islands, packages, stylesheets, production builds) is complete and tested against real applications, including a [Mantine](https://nitefx.dev/docs/guides/mantine.md) app and a [Tailwind CSS 4](https://nitefx.dev/docs/guides/tailwind.md) app. The packages are [on NuGet](https://www.nuget.org/packages/Nite.Cli), so [installation](https://nitefx.dev/docs/getting-started.md#install-nitefx) is one `dotnet tool install`.

## Next steps

- [Getting started](https://nitefx.dev/docs/getting-started.md): install the CLI and create your first app.
- [Tutorial](https://nitefx.dev/docs/tutorial.md): build a small full-stack app and see each part of the dev loop.
- [How NiteFx works](https://nitefx.dev/docs/concepts/architecture.md): the moving parts, for when you want to know what happens on save.


<!-- Source: https://nitefx.dev/docs/getting-started.html -->

# 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](https://nitefx.dev/docs/guides/private-registries.md).

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](https://nitefx.dev/docs/code-signing.md).

# [NuGet (recommended)](https://nitefx.dev/docs/getting-started.md#tab/nuget)

```bash
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`.

# [Reference a source checkout](https://nitefx.dev/docs/getting-started.md#tab/source)

If you are working on NiteFx itself, point new projects at your checkout instead. The project then references `src/Nite` and `src/Nite.Cli` directly, so changes to NiteFx take effect on the next build.

```bash
git clone https://github.com/nite-net/nite
cd nite && dotnet build

# Run the CLI from the checkout.
dotnet run --project src/Nite.Cli -- init ../my-app --nite-source .
```

Inside such a project, run the CLI the same way (`dotnet run --project <nite>/src/Nite.Cli -- watch`), or install the tool from NuGet as in the other tab.

---

## Create an app

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

# [Single-page app](https://nitefx.dev/docs/getting-started.md#tab/spa)

```bash
nite init my-app
cd my-app
```

```text
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)
```

# [Razor Pages with islands](https://nitefx.dev/docs/getting-started.md#tab/islands)

```bash
nite init my-site --template islands
cd my-site
```

```text
my-site/
  my-site.csproj
  Program.cs              Razor Pages, AddNite, UseNite
  nite.json
  Pages/
    _ViewImports.cshtml   @addTagHelper *, Nite
    Shared/_Layout.cshtml <nite-head /> in <head>
    Index.cshtml          <island name="Counter" props="new { start = 0 }">
  Client/
    islands/Counter.tsx   a React component used as an island
  wwwroot/site.css
```

---

> [!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:

```bash
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

```bash
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](https://nitefx.dev/docs/guides/hot-reload.md).

## Add a package

```bash
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](https://nitefx.dev/docs/guides/packages.md).

## Publish

```bash
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](https://nitefx.dev/docs/guides/deployment.md).

## Already have a Vite app?

```bash
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](https://nitefx.dev/docs/guides/importing.md).

## 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`](https://nitefx.dev/llms.txt) is an index, [`/llms-full.txt`](https://nitefx.dev/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

- [Tutorial: a full-stack app](https://nitefx.dev/docs/tutorial.md) builds on the SPA template step by step.
- [Single-page apps](https://nitefx.dev/docs/guides/single-page-apps.md) and [Islands](https://nitefx.dev/docs/guides/islands.md) cover each model in depth.
- [nite.json reference](https://nitefx.dev/docs/reference/nite-json.md) lists every setting.


<!-- Source: https://nitefx.dev/docs/tutorial.html -->

# Tutorial: a full-stack app

Build a todo app with a minimal API and a React frontend in one project. Along the way you will use Fast Refresh, C# hot reload that reaches the page, client-side routing, CSS modules, environment variables and a production publish.

You need NiteFx installed ([Getting started](https://nitefx.dev/docs/getting-started.md#install-nitefx)). The whole tutorial takes about half an hour.

## 1. Create the project

```bash
nite init todos
cd todos
nite watch
```

The browser opens on the template's page. Leave `nite watch` running for the rest of the tutorial; every step below is a save, not a restart.

## 2. Write the API

Replace `Program.cs` with an in-memory store and a few endpoints:

```csharp
using System.Collections.Concurrent;
using Nite;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddNite();
builder.Services.AddSingleton<TodoStore>();

var app = builder.Build();
app.UseNite();

var api = app.MapGroup("/api");
api.MapGet("/todos", (TodoStore store) => store.All());
api.MapPost("/todos", (NewTodo input, TodoStore store) =>
    string.IsNullOrWhiteSpace(input.Title)
        ? Results.ValidationProblem(new Dictionary<string, string[]> { ["title"] = ["A title is required."] })
        : Results.Created("/api/todos", store.Add(input.Title.Trim())));
api.MapPatch("/todos/{id:int}", (int id, TodoPatch patch, TodoStore store) =>
    store.SetDone(id, patch.Done) is { } todo ? Results.Ok(todo) : Results.NotFound());

app.MapStaticAssets();
app.MapNiteSpa();
app.Run();

record Todo(int Id, string Title, bool Done);
record NewTodo(string Title);
record TodoPatch(bool Done);

class TodoStore
{
    private readonly ConcurrentDictionary<int, Todo> _todos = new();
    private int _nextId;

    public TodoStore()
    {
        Add("Write the API in C#");
        Add("Write the UI in React");
    }

    public IReadOnlyList<Todo> All() => _todos.Values.OrderBy(t => t.Id).ToList();

    public Todo Add(string title)
    {
        var todo = new Todo(Interlocked.Increment(ref _nextId), title, false);
        _todos[todo.Id] = todo;
        return todo;
    }

    public Todo? SetDone(int id, bool done) =>
        _todos.TryGetValue(id, out var todo) ? _todos[id] = todo with { Done = done } : null;
}
```

New endpoints and a new service need a restart, so `nite watch` restarts the app. The page waits for the server to come back and reloads (about ten seconds). Check the API directly at `/api/todos`.

> [!NOTE]
> `app.MapNiteSpa()` serves `Client/index.html` for every path without a file extension, **except** paths under `/api`. A mistyped API URL gets a 404, not a page of HTML.

## 3. A typed API client

Create `Client/api.ts`:

```ts
// Same origin as the ASP.NET Core app: no CORS, no proxy, no base URL.
export type Todo = { id: number; title: string; done: boolean };

async function request<T>(url: string, init?: RequestInit): Promise<T> {
  const response = await fetch(url, {
    ...init,
    headers: { "Content-Type": "application/json", ...init?.headers },
  });
  if (!response.ok) throw new Error(`${init?.method ?? "GET"} ${url}: ${response.status}`);
  return response.json() as Promise<T>;
}

export const api = {
  todos: () => request<Todo[]>("/api/todos"),
  add: (title: string) => request<Todo>("/api/todos", { method: "POST", body: JSON.stringify({ title }) }),
  setDone: (id: number, done: boolean) =>
    request<Todo>(`/api/todos/${id}`, { method: "PATCH", body: JSON.stringify({ done }) }),
};

/** Runs `callback` when C# hot reload changes the server. Returns the unsubscribe function. */
export function onServerUpdate(callback: () => void) {
  addEventListener("nite:server-update", callback);
  return () => removeEventListener("nite:server-update", callback);
}
```

Nothing reloads when you save this file: no module on the page imports it yet.

## 4. The todo list

Create `Client/TodoList.tsx`:

```tsx
import { useEffect, useState, type FormEvent } from "react";
import { api, onServerUpdate, type Todo } from "./api";

export function TodoList() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [draft, setDraft] = useState("");

  useEffect(() => {
    const load = () => api.todos().then(setTodos);
    load();
    return onServerUpdate(load);
  }, []);

  async function add(event: FormEvent) {
    event.preventDefault();
    if (!draft.trim()) return;
    const todo = await api.add(draft);
    setTodos((current) => [...current, todo]);
    setDraft("");
  }

  async function toggle(todo: Todo) {
    const updated = await api.setDone(todo.id, !todo.done);
    setTodos((current) => current.map((t) => (t.id === updated.id ? updated : t)));
  }

  return (
    <section>
      <h1>Todos</h1>
      <ul>
        {todos.map((todo) => (
          <li key={todo.id}>
            <label>
              <input type="checkbox" checked={todo.done} onChange={() => toggle(todo)} /> {todo.title}
            </label>
          </li>
        ))}
      </ul>
      <form onSubmit={add}>
        <input value={draft} onChange={(e) => setDraft(e.target.value)} placeholder="What needs doing?" />
        <button>Add</button>
      </form>
    </section>
  );
}
```

And render it from `Client/App.tsx`:

```tsx
import { TodoList } from "./TodoList";

export function App() {
  return (
    <main>
      <TodoList />
    </main>
  );
}
```

The page updates without a reload.

## 5. Feel Fast Refresh

Type something into the "What needs doing?" box, but do not submit it. Now edit `TodoList.tsx`: change `<h1>Todos</h1>` to `<h1>Things to do</h1>` and save.

The heading changes in about 150 ms, and your half-typed text is still there. NiteFx found that `TodoList.tsx` exports only components, re-imported just that module, and let React swap the new function in while keeping its state. Edits to `api.ts` work too: NiteFx walks up from the changed module to the components that import it and refreshes those.

What resets state, and why:

- **Adding or removing a hook** in a component remounts that component (its hook list changed, so old state cannot map onto it).
- **Editing `main.tsx`** reloads the page: the entry module has no component boundary above it.

## 6. C# changes reach the page

Change the seed data in `TodoStore`'s constructor, or the validation message, and save `Program.cs`. Hot reload applies the change in the running app and NiteFx sends the page a `nite:server-update` event; `TodoList` re-fetches through `onServerUpdate`, and the list updates with nothing reloaded.

> [!TIP]
> The event never fires in production, so `onServerUpdate` costs nothing there. Use it in any component that shows server data.

## 7. Routing

Add React Router:

```bash
nite add react-router
```

The running dev server notices `nite.json` changed, pre-bundles the package and reloads the page. Wrap the app in a router in `Client/main.tsx`:

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter } from "react-router";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </StrictMode>,
);
```

Add an about page and routes in `Client/App.tsx`:

```tsx
import { NavLink, Route, Routes } from "react-router";
import { TodoList } from "./TodoList";

function About() {
  return <p>A todo app with an ASP.NET Core API and a React frontend, built with nite.</p>;
}

export function App() {
  return (
    <>
      <nav>
        <NavLink to="/" end>Todos</NavLink> · <NavLink to="/about">About</NavLink>
      </nav>
      <main>
        <Routes>
          <Route path="/" element={<TodoList />} />
          <Route path="/about" element={<About />} />
        </Routes>
      </main>
    </>
  );
}
```

Open `/about` directly in a new tab: `MapNiteSpa` serves `index.html` for it, and the router takes over.

## 8. Scoped styles with a CSS module

Create `Client/TodoList.module.css`:

```css
.list {
  list-style: none;
  padding: 0;
}

.done {
  color: gray;
  text-decoration: line-through;
}
```

Use it in `TodoList.tsx`:

```tsx
import styles from "./TodoList.module.css";

// ...
<ul className={styles.list}>
  {todos.map((todo) => (
    <li key={todo.id} className={todo.done ? styles.done : undefined}>
```

Class names are scoped to the file, so `.done` here never collides with a `.done` anywhere else. Edit the CSS and save: the components using it refresh in place. Plain `.css` files, Sass, Less, Tailwind and PostCSS work the same way; see [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md).

## 9. Configuration from the environment

Create `.env` in the project folder (next to `nite.json`):

```ini
NITE_PUBLIC_APP_NAME=Todos
DATABASE_PASSWORD=never-reaches-the-browser
```

Use it in `TodoList.tsx`:

```tsx
<h1>{import.meta.env.NITE_PUBLIC_APP_NAME}</h1>
```

Only variables starting with `NITE_PUBLIC_` reach client code; the password stays on the server. Editing `.env` reloads the page with the new values. See [Environment variables](https://nitefx.dev/docs/guides/environment.md).

## 10. Publish

Stop `nite watch` (Ctrl+C) and publish:

```bash
dotnet publish -c Release -o publish
cd publish
dotnet todos.dll
```

The Release build ran `nite build`: `publish/wwwroot/_nite` holds the minified, content-hashed bundles (with `.br` and `.gz` copies) and `index.html` pointing at them. `MapNiteSpa` serves that built page, and `MapStaticAssets` serves the bundles, compressed with Brotli for browsers that accept it. The published app has no `node_modules`, no esbuild and no dev server.

## What you used

| Step | Feature | Read more |
|---|---|---|
| 2 | A restart for a structural C# change, handled by `nite watch` | [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md) |
| 4, 5 | Fast Refresh and the module graph | [How NiteFx works](https://nitefx.dev/docs/concepts/architecture.md) |
| 6 | `nite:server-update` | [Browser runtime](https://nitefx.dev/docs/reference/browser-runtime.md) |
| 7 | `nite add`, `MapNiteSpa` fallback routing | [Packages](https://nitefx.dev/docs/guides/packages.md), [Single-page apps](https://nitefx.dev/docs/guides/single-page-apps.md) |
| 8 | CSS modules | [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md) |
| 9 | `.env` and `envPrefix` | [Environment variables](https://nitefx.dev/docs/guides/environment.md) |
| 10 | `nite build` and `MapStaticAssets` | [Deployment](https://nitefx.dev/docs/guides/deployment.md) |


<!-- Source: https://nitefx.dev/docs/concepts/architecture.html -->

# How NiteFx works

NiteFx does the orchestration in .NET and hands compilation to esbuild. This page walks through each piece, roughly in the order a request meets them.

```text
 browser ──GET /_nite/src/App.tsx──▶ ASP.NET Core app
                                      │  UseNite(): NiteDevServer
                                      │    ├─ transform (esbuild service) ─▶ cached JS
                                      │    ├─ rewrite imports (import map, ?import, ?t=)
                                      │    └─ Fast Refresh registration
 browser ◀──────── ESM module ────────┘
 browser ◀──WebSocket /_nite/ws── file watcher ─▶ module graph ─▶ update / css / reload
```

## esbuild, as a service

[esbuild](https://esbuild.github.io) compiles TypeScript and JSX. NiteFx downloads the platform's binary from the same npm package esbuild's own installer uses (`@esbuild/linux-x64`, `@esbuild/darwin-arm64` and so on), verifies it against the registry's integrity hash, and caches it per user.

It does not run esbuild once per file. It starts one `esbuild --service` process and keeps it for the life of the app, talking esbuild's binary stdio protocol: the same channel esbuild's JavaScript API uses. Transforms take a few milliseconds and run concurrently. Builds can call back into .NET through esbuild's plugin protocol, which is how stylesheets reach the [CSS pipeline](https://nitefx.dev/docs/concepts/architecture.md#the-stylesheet-pipeline).

## Packages without npm

A small npm client written in C# reads `dependencies` and `devDependencies` from `nite.json`, resolves semver ranges against the registry, and installs into an ordinary `node_modules` folder, hoisted the way npm does it. Editors, the TypeScript language service and esbuild all find packages where they expect them.

- Resolution is recorded in **`nite.lock.json`**. With a current lockfile, an install never asks the registry for metadata.
- Tarballs are verified against their integrity hash and cached per user.
- **Install scripts never run.** Packages that need a `postinstall` step (native addons, mostly) do not work; NiteFx warns when it resolves one.
- Optional dependencies are skipped.

See [Packages and the lockfile](https://nitefx.dev/docs/guides/packages.md).

## The dev server

`app.UseNite()` mounts the dev server at `/_nite`, inside your app, in the Development environment only. Each source file is compiled on request and cached until it changes. Before serving a module, NiteFx rewrites its import specifiers:

| In your code | Served as | Why |
|---|---|---|
| `import { x } from "./util"` | `./util.ts` | One canonical URL per file, so a module is never instantiated twice. |
| `import logo from "./logo.svg"` | `./logo.svg?import` | Non-JavaScript imports become small JavaScript modules (a URL, CSS, JSON). |
| `import "react"` | `react` (unchanged) | Bare imports resolve through an **import map** to pre-bundled dependencies. |
| A module that just changed | `./Button.tsx?t=1729…` | The timestamp makes importers fetch the new version. |

Path aliases from your tsconfig (`@/components/Button`) are resolved the same way. The full URL layout is in [Dev server URLs](https://nitefx.dev/docs/reference/dev-server-urls.md).

## Dependency pre-bundling

Browsers can import ES modules, but most packages are not shaped for it: React is still CommonJS, and a package can be hundreds of files. Like Vite, NiteFx pre-bundles every bare import your code uses into a single ESM file per package, in **one** esbuild pass with code splitting, so `react-dom` and your code share one copy of React.

CommonJS packages get a generated wrapper whose named exports come from a scan of the package's code (the same approach as Node's `cjs-module-lexer`), so `import { useState } from "react"` works. The result is cached under `.nite/deps` and only rebuilt when your bare imports or the lockfile change. Importing a package for the first time while the app runs triggers a re-bundle and a page reload.

## React Fast Refresh, without Babel

esbuild has no Fast Refresh transform, so NiteFx adds one after the fact. It reads esbuild's output for each JSX or TSX module and:

1. finds components by shape: PascalCase functions, arrow functions assigned to PascalCase names, `memo` and `forwardRef` wrappers, and default exports that are components;
2. registers each with `react-refresh`'s runtime and signs it with its hook calls, so a change in hook order is detected;
3. marks the module a **refresh boundary** if every export is a component.

A module graph records who imports what among the modules the browser has loaded. When a file changes, NiteFx walks up from it to the nearest boundaries, recompiles, and tells the browser to re-import those modules with a new timestamp. React then swaps the new implementations in and keeps state. If the walk reaches the page's entry module (`main.tsx`), nothing can accept the update, and the page reloads.

## The file watcher and the browser client

A file watcher on the client folder debounces saves (editors often write in several steps) and decides, per change:

| Change | Message to the browser |
|---|---|
| A component module, or a module only components import | `update`: re-import the boundaries |
| A stylesheet, or a file a stylesheet depends on | `css`: swap the stylesheet in place |
| A CSS module | `update` for the components that import it |
| `index.html`, the entry module, a deleted file | `reload` |
| A compile error | `error`: show the overlay; the next good save clears it |
| `nite.json` | Install, re-bundle, `reload` |
| `.env*`, `tsconfig*.json` | Recompile, `reload` |

The browser client (`/_nite/client.js`) receives these over a WebSocket at `/_nite/ws`. If the socket drops (the server restarting under `dotnet watch`), it reconnects and reloads, waiting until the server answers first so the tab never lands on a "can't connect" page.

## C# hot reload, forwarded

NiteFx registers a .NET `MetadataUpdateHandler`. When `dotnet watch` applies a C# change inside the running app, the runtime calls it, and the dev server broadcasts a `server-update` message. The client turns that into a `nite:server-update` DOM event, which pages use to re-fetch data. See [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md).

## The stylesheet pipeline

Stylesheets go through the same steps as in Vite, in development and production:

1. **Sass** (`.scss`, `.sass`) or **Less** (`.less`), by extension;
2. **Tailwind CSS 4**, when the file uses it;
3. **PostCSS**, when the project has a config;
4. **esbuild**: `@import` inlining, CSS modules, `url()` assets, and in production, minifying and lowering.

Sass runs as the native Dart Sass binary over its embedded protocol, one long-lived compiler like esbuild. PostCSS (with your plugins), Tailwind's compiler and Less are plain JavaScript: NiteFx bundles them from your `node_modules` with esbuild and runs them in [Jint](https://github.com/sebastienros/jint), a JavaScript interpreter written in C#, with a small shim for the Node built-ins they use. Tailwind's file scanner is native code, so NiteFx has its own in C#; it scans the whole project, including Razor views. See [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md).

## The production build

`nite build` (which `dotnet publish` runs for Release builds) does one esbuild build for every entry: islands, HTML pages and the modules listed in `entries`. The output is minified, split into shared chunks, content-hashed and written to `wwwroot/_nite` with a `manifest.json` that maps each entry to its files, CSS and preloads.

At runtime in production, `UseNite()` does nothing. The tag helpers and `MapNiteSpa` read the manifest, and `MapStaticAssets` serves the files (precompressed with Brotli and gzip by the static web assets pipeline). See [Development and production](https://nitefx.dev/docs/concepts/development-and-production.md).

## Where things live

| Path | What | Commit it? |
|---|---|---|
| `nite.json` | Packages and settings | Yes |
| `nite.lock.json` | Resolved package versions | Yes |
| `node_modules/` | Installed packages | No |
| `.nite/` | Dev server cache: pre-bundled dependencies, bundled CSS tools | No |
| `wwwroot/_nite/` | Production build output | No (built on publish) |
| `~/.cache/nite/` | Per-user download cache: tarballs, registry metadata, esbuild, Sass | Not in the project |


<!-- Source: https://nitefx.dev/docs/concepts/project-layout.html -->

# Project layout

A NiteFx project is an ordinary ASP.NET Core project with a client folder and a `nite.json` next to the project file.

## A single-page app

```text
MyApp/
  MyApp.csproj
  AGENTS.md                  instructions for AI coding agents
  Program.cs                 AddNite, UseNite, your API, MapNiteSpa
  nite.json                  client packages and settings
  nite.lock.json             resolved package versions
  .env                       optional; NITE_PUBLIC_* values reach the client
  Client/                    the client root ("clientRoot" in nite.json)
    index.html               the entry page
    main.tsx                 the entry module
    App.tsx
    styles.css
    tsconfig.json
  wwwroot/                   static files served as-is (favicon, robots.txt, images)
  node_modules/              installed packages
  .nite/                     dev server cache
```

## Razor Pages with islands

```text
MySite/
  MySite.csproj
  AGENTS.md
  Program.cs                 AddRazorPages, AddNite, UseNite
  nite.json
  nite.lock.json
  Pages/
    _ViewImports.cshtml      @addTagHelper *, Nite
    Shared/_Layout.cshtml    <nite-head /> inside <head>
    Index.cshtml             <island name="Counter" ... />
  Client/
    islands/                 every module here can be an <island> ("islands" in nite.json)
      Counter.tsx
      admin/UserTable.tsx    used as <island name="admin/UserTable" />
    lib/                     shared code, not islands
  wwwroot/site.css
```

Both models can live in one project: an `index.html` in the client root and an islands folder work side by side.

## The client root

Everything NiteFx compiles lives under the client root, `Client` by default. In development its files are served under `/_nite/src/`, so `Client/App.tsx` is `/_nite/src/App.tsx`. Nothing outside the client root is served by the dev server, with two exceptions: packages from `node_modules` (pre-bundled under `/_nite/deps/`, or as files under `/_nite/npm/`) and the dev runtime itself.

Change it with `"clientRoot"` in `nite.json`. Islands are looked up in `"islands"` relative to the client root.

## Files NiteFx reads

| File | Read by | Purpose |
|---|---|---|
| `nite.json` | Dev server, CLI, build | Packages and settings. Reloaded live in development. [Reference](https://nitefx.dev/docs/reference/nite-json.md). |
| `nite.lock.json` | Installer | Exact versions. Written by installs; do not edit by hand. |
| `Client/tsconfig.json` (and what it `extends` or `references`) | Dev server, build | `compilerOptions.paths` aliases; the build uses the file that declares them. |
| `.env`, `.env.local`, `.env.development`, `.env.production`, `.env.*.local` | Dev server, build | Public environment variables. [Guide](https://nitefx.dev/docs/guides/environment.md). |
| `postcss.config.*`, `.postcssrc*`, `package.json` `"postcss"` | CSS pipeline | PostCSS plugins. Looked up in the client root, then the project folder. |
| `.npmrc` (project and user) | Installer | Registries and credentials. [Guide](https://nitefx.dev/docs/guides/private-registries.md). |
| `.gitignore` | Tailwind scanner | Folders to skip when looking for class names. |

## Files NiteFx writes

| Path | Contents | In git? |
|---|---|---|
| `nite.lock.json` | Resolved versions and integrity hashes | **Yes** |
| `node_modules/` | Installed packages | No |
| `node_modules/.nite-state.json` | What the last install wrote, for cleanup | No |
| `.nite/deps/` | Pre-bundled dependencies | No |
| `.nite/tools/` | PostCSS, Tailwind and Less bundled for the JavaScript engine | No |
| `.nite/css/`, `.nite/runtime/` | Scratch files for stylesheet and production builds | No |
| `wwwroot/_nite/` | Production build output | No |

The `.gitignore` that `nite init` writes covers all of these:

```text
bin/
obj/
node_modules/
.nite/
wwwroot/_nite/
.env*.local
```

## Build integration

The `Nite` package brings MSBuild targets that:

- keep `node_modules` and `.nite` out of the project's default items, so the build does not walk thousands of files;
- never copy the client sources, `nite.json` or `nite.lock.json` to the build or publish output;
- run `nite build` before Release builds and include `wwwroot/_nite` in the publish output;
- remove `wwwroot/_nite` on `dotnet clean`.

See [MSBuild properties](https://nitefx.dev/docs/reference/msbuild.md).


<!-- Source: https://nitefx.dev/docs/concepts/development-and-production.html -->

# Development and production

The same `Program.cs` runs a compiling dev server in development and serves prebuilt static files in production. This page explains the switch and the differences.

## Which mode am I in?

`AddNite()` picks the mode from the hosting environment: **development** when `IWebHostEnvironment.IsDevelopment()` is true (`ASPNETCORE_ENVIRONMENT=Development`), **production** otherwise. Override it with [Nite.NiteOptions](https://nitefx.dev/api/Nite.NiteOptions.html):

```csharp
builder.Services.AddNite(options =>
{
    // Serve the production build even in Development, to check it locally.
    options.Mode = NiteMode.Production;
});
```

`NiteMode.Development` does the opposite: the dev server in a Staging environment, say.

## What changes

| | Development | Production |
|---|---|---|
| `UseNite()` | Mounts the dev server at `/_nite` and starts the file watcher | Does nothing |
| Source files | Compiled on request, cached until they change | Built ahead of time by `nite build` |
| Packages | Installed on startup from `nite.lock.json`; pre-bundled into `.nite/deps` | Bundled into the output chunks |
| `MapNiteSpa()` | Serves `Client/index.html` from source, with the dev client injected | Serves `wwwroot/_nite/index.html` with hashed URLs |
| `<island>`, `<nite-module>`, `<nite-head>` | Point at `/_nite/src/...` and the import map | Point at hashed files from `manifest.json` |
| CSS imported from code | Injected as `<style>` tags by the importing module | Extracted to `.css` files and linked |
| `import.meta.env.MODE` | `"development"` | `"production"` |
| `process.env.NODE_ENV` | `"development"` | `"production"` |
| Source maps | Inline | Separate `.map` files |
| Minification | None | Yes |
| Errors | Overlay in the page | Build fails |

## Startup in development

On the first request, the dev server:

1. downloads esbuild if this machine has not cached it;
2. installs packages if `node_modules` does not match `nite.lock.json` (a no-op when it does);
3. compiles every module in the client root once, to discover all bare imports;
4. pre-bundles those dependencies (skipped when nothing changed since last time) and, in parallel, warms up the stylesheet tools the project uses.

Requests wait for this to finish, so the first page load is complete rather than a cascade of reloads. On a warm cache it takes about as long as the app takes to start.

## The production build

`nite build` runs before Release builds (and therefore before `dotnet publish -c Release`). It writes:

```text
wwwroot/_nite/
  manifest.json              entry → file, CSS, preloads
  index.html                 the SPA page with hashed URLs (if Client/index.html exists)
  main-MUGH3OMJ.js           an entry, at its path under the client root (Client/main.tsx)
  styles-V7BMX6ER.css        a stylesheet linked from index.html
  islands/Counter-AB12CD34.js
  islands-runtime-….js       the island loader and renderer (if there are islands)
  chunks/…                   code shared between entries
  assets/…                   images and fonts referenced from code or CSS
  *.map                      source maps
```

Entries keep their folder: `Client/src/main.tsx` becomes `src/main-<hash>.js`. CSS that a module imports is collected into one `.css` file per entry, next to it.

Production assumes the build output is present. If `manifest.json` is missing, `MapNiteSpa` and the tag helpers fail with a message telling you to run `nite build`. See [Production builds and deployment](https://nitefx.dev/docs/guides/deployment.md).

## Checking the production build locally

```bash
nite build
ASPNETCORE_ENVIRONMENT=Production dotnet run --no-launch-profile
```

Or set `options.Mode = NiteMode.Production` temporarily, as above. For an exact rehearsal of a deployment, publish and run the output: `dotnet publish -c Release -o publish && dotnet publish/MyApp.dll`. `dotnet clean` removes `wwwroot/_nite` again; Debug builds never include it, so a stale production build cannot leak into development.


<!-- Source: https://nitefx.dev/docs/limits.html -->

# Limits and non-goals

NiteFx is intentionally smaller than Vite. Knowing where the edges are before you start saves you finding them halfway through a project.

## Non-goals

**Vite and Rollup plugins.** Vue single-file components, Svelte, Astro, MDX and similar need Vite's plugin pipeline and a JavaScript runtime in the build. If your project depends on them, Vite is the right tool. (PostCSS plugins and Tailwind plugins do work: see [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md).)

**Server-side rendering of components.** Islands render on the client; use the fallback content inside `<island>` for what the server shows first. Meta-frameworks with their own servers (Next.js, Remix, Nuxt) are out of scope.

**Type checking.** Like Vite, NiteFx strips types without checking them, so compiling stays fast. Your editor checks as you type; run `tsc --noEmit` in CI. See [TypeScript](https://nitefx.dev/docs/guides/typescript.md#type-checking).

**Running arbitrary Node tooling.** NiteFx does not provide a Node-compatible runtime for your scripts: linters, test runners and code generators keep running however you run them today.

## Packages

- **Registry packages only.** `git:`, `file:`, `link:`, `workspace:`, tarball URLs and `npm:` aliases are not supported.
- **Install scripts never run.** Packages that compile native addons or download binaries in `postinstall` do not work. NiteFx warns about them when it resolves them ([Install scripts](https://nitefx.dev/docs/guides/packages.md#install-scripts)).
- **Optional dependencies are skipped.**
- **No `overrides` or `resolutions`.** Versions come from the ranges, the lockfile and `nite update`.
- **No workspaces.** One `nite.json` per project.

## Compilation

- **Fast Refresh is heuristic.** Components are found in esbuild's output by shape: PascalCase functions, arrow functions, `memo` and `forwardRef`. Class components and other higher-order components refresh by propagating to their importers. If a custom hook changes its internal hook order, save again or reload.
- **No Babel plugins** and no syntax that needs one.
- **No `import.meta.glob`**, and no Vite import suffixes (`?raw`, `?url`, `?worker`, `?inline`). Use explicit imports, `fetch`, and `new Worker(new URL("./worker.ts", import.meta.url), { type: "module" })`.
- **SVGs import as URLs**, not as React components (no svgr).

## Stylesheets

- **No Stylus.**
- **Tailwind CSS 4 only**, not 3.
- **PostCSS and Tailwind plugins must be plain JavaScript**, since they run in an interpreter. The interpreter is also slower than Node: the first Tailwind compile in a session takes a second or two.
- **CSS that a package's own JavaScript imports** is not collected; import the package's stylesheet from your code.
- **No `css.modules` options** such as `localsConvention`.
- **Relative `url()`s inside Sass partials** are not rebased to the partial's folder.

## Hosting

- **Production asset URLs assume the site root.** Bundles and chunks load from `/_nite/...`. HTML from `MapNiteSpa` and the tag helpers include the request's path base, but URLs inside JavaScript and CSS (lazy chunks, `url()` assets) do not, so hosting under a subfolder (`/shop`) does not fully work yet.
- **Hashed bundles are revalidated, not cached as immutable.** `MapStaticAssets` serves them with `ETag`s and `no-cache`, so repeat visits cost a `304` per file. A CDN rule can cache `/_nite/*` long-term safely.

## Platform

- **.NET 10** and ASP.NET Core 10.
- **Linux, macOS and Windows on x64 and Arm64.** Other platforms work wherever esbuild (and, for Sass, Dart Sass) publish binaries, or with `NITE_ESBUILD_PATH` / `NITE_SASS_PATH`.

## Status

NiteFx is at version 0.8. APIs outside `AddNite`, `UseNite`, `MapNiteSpa`, the tag helpers and `nite.json` may change between minor versions. Bugs and gaps are tracked on [GitHub](https://github.com/nite-net/nite/issues). Which of these limits go away next is on the [roadmap](https://nitefx.dev/docs/roadmap.md).


<!-- Source: https://nitefx.dev/docs/roadmap.html -->

# Roadmap

What we plan to build next, in order. These are plans, not promises: priorities change when you tell us what hurts. Open or vote on an [issue](https://github.com/nite-net/nite/issues) to move something up.

Released work is in the [changelog](https://nitefx.dev/docs/changelog.md); what NiteFx deliberately does not do is in [Limits and non-goals](https://nitefx.dev/docs/limits.md).

## 0.9: safer and faster production builds

Small changes that close gaps in [Limits](https://nitefx.dev/docs/limits.md) and continue the security work in 0.8.

- **Subresource integrity.** Production scripts and the import map carry `integrity` hashes, so a CDN or proxy that alters a bundle gets it refused by the browser. Pairs with the [Content Security Policy](https://nitefx.dev/docs/reference/aspnet.md#content-security-policy) support in 0.8.
- **Immutable caching for hashed files.** Bundles, chunks and assets have content hashes in their names but are served with `no-cache` today, which costs a `304` per file on every visit. They will be served as `immutable` instead.
- **A minimum release age for packages.** A setting in `nite.json` (for example `"minimumReleaseAge": "3d"`) makes `nite add` and `nite update` pass over versions published more recently than that. Malicious package versions are usually found and removed within days, so waiting a few days avoids most of them.
- **`?raw` and `?url` imports**, and SVGs imported as React components, for code coming from Vite.
- **Hosting under a path base.** URLs inside production JavaScript and CSS (lazy chunks, `url()` assets) work when the app is served from a subfolder such as `/shop`, not only from the site root.

## 0.10: knowing and fixing vulnerable packages

- **`nite audit`.** Checks every package in `nite.lock.json` against the npm advisory database and reports known vulnerabilities. `nite build` can fail on them above a severity you choose, so CI catches them.
- **`overrides`.** Pin a dependency of a dependency to a patched version without waiting for every package above it to release one. These two ship together: a report you cannot act on is only half a feature.

## 1.0: one set of types from C# to TypeScript

- **Generated API types.** ASP.NET Core already describes your endpoints as an OpenAPI document. In development, NiteFx will turn it into TypeScript types and a typed `fetch` wrapper, and refresh them on every C# hot reload, so renaming a property on a C# record shows up as a type error in the TypeScript that uses it. The same will cover [client config](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server) when it returns a named type.
- **A stable API.** From 1.0, NiteFx follows semantic versioning for its whole public surface, not only `AddNite`, `UseNite`, `MapNiteSpa`, the tag helpers and `nite.json`.

## Not planned

These come up, and the answer is no for now, for these reasons:

- **Platform-specific optional dependencies.** NiteFx already fetches the right esbuild and Dart Sass binaries for each platform. Most other packages that need this are native Node addons, which cannot run in a browser. If a browser package you need depends on it, open an issue with its name.
- **Built-in type checking.** It needs Node, or a JavaScript interpreter that would make every save slow. Run `tsc --noEmit` in your editor and CI; the generated API types in 1.0 add the checking NiteFx can do best.
- **Server-side rendering, and Vue, Svelte or other Vite plugins.** See [Limits and non-goals](https://nitefx.dev/docs/limits.md#non-goals).
- **A security-headers package.** Headers like a Content Security Policy are your application's policy, and a library default is one nobody revisits. NiteFx gives you the hooks (`NiteOptions.CspNonce`), and [`samples/Nite.Identity`](https://github.com/nite-net/nite/tree/main/samples/Nite.Identity) shows a complete, strict setup to copy.


<!-- Source: https://nitefx.dev/docs/troubleshooting.html -->

# Troubleshooting

Symptoms, their usual causes, and the fix. Run CLI commands with `--verbose` for debug output; in the app, raise the `Nite` log category to `Debug` in `appsettings.Development.json`.

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Nite": "Debug"
    }
  }
}
```

## Installing and starting

### "Package 'x' is not installed. Add it to dependencies in nite.json."

Code imports a package that is not in `node_modules`. Run `nite add x`. If it is in `nite.json` already, run `nite install` and check the output for errors.

### The first start is slow, or fails without network

The first run downloads esbuild and your packages. Later runs use the cache (`~/.cache/nite`) and the lockfile. Behind a proxy or without registry access, see [Private registries](https://nitefx.dev/docs/guides/private-registries.md) and [Offline machines](https://nitefx.dev/docs/reference/environment-variables.md#offline-and-air-gapped-machines).

### "'name@range' is not supported. Nite installs registry versions and ranges only."

A dependency uses `git:`, `file:`, `workspace:`, a URL or an `npm:` alias. Publish the package to a registry, or vendor its code into the client folder.

### A package fails at runtime with errors about a missing binary or `.node` file

It needs an install script or a native addon, which NiteFx does not run. NiteFx warns about packages with install scripts when it resolves them ([Install scripts](https://nitefx.dev/docs/guides/packages.md#install-scripts)); run `nite update <package>` to see the message again. Look for a pure-JavaScript alternative, or a browser build of the package.

### "This nite is not running as a dotnet tool"

`nite update-self` only works for an installed tool. Running from a source checkout, pull and rebuild instead.

## Development

### Edits do not show up

- Check the file is under the client root (`Client/` by default). Files elsewhere are not watched, except Razor views for Tailwind.
- Check the page actually loads the module. Edits to files nothing imports do nothing, by design.
- Check the browser console for `[nite]` messages (they log at the `debug` level, so enable verbose logs) and for WebSocket errors.

### Every component edit reloads the page

Fast Refresh needs React as a dependency, `jsxImportSource` set to `react` and `fastRefresh` not `false`. If those are right, the edited module probably exports something besides components, so it is not a refresh boundary; move the non-component exports to another file. See [How Fast Refresh decides](https://nitefx.dev/docs/guides/hot-reload.md#how-fast-refresh-decides).

### "Rendered more hooks than during the previous render" after an edit

A custom hook changed the order of the hooks it calls, which hook signatures do not see. Save again or reload.

### Adding an endpoint in Program.cs does nothing

`dotnet watch` treated the edit as one that "might not have any effect until the application is restarted" (ENC0118) and waited for Ctrl+R. `nite watch` restarts automatically; with plain `dotnet watch`, set `DOTNET_WATCH_RESTART_ON_RUDE_EDIT=1`. See [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md#changes-that-need-a-restart).

### The page reloads after every C# change

Plain `dotnet watch` injects a reload script. Use `nite watch`, or set `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH=1` in the environment (it is ignored in `launchSettings.json`).

### A Tailwind class has no effect

- Make sure the class name appears in full somewhere in the project, not assembled from pieces (`` `text-${color}-600` `` is never found).
- Check the file is not in a folder your `.gitignore` lists, or add `@source "<folder>"`.
- Tailwind 3 is not supported; check `nite list` shows `tailwindcss` 4.

### "Nite supports Tailwind CSS 4; this project has 3.x"

Upgrade with `npx @tailwindcss/upgrade` and the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).

### A PostCSS plugin fails with "Cannot find module" or a native addon error

The plugin needs a Node built-in NiteFx does not provide, or native code. Check the plugin's issue tracker for a browser-compatible build, or remove it. Run with `Nite` logging at `Debug` to see the full error.

### "Sass stylesheets need the sass-embedded (or sass) package"

Install it: `nite add -D sass-embedded`. NiteFx uses its version to download the matching native compiler.

### An island does not mount

- `<nite-head />` must be in the layout's `<head>`.
- `@addTagHelper *, Nite` must be in `_ViewImports.cshtml`; without it, `<island>` is rendered as an unknown HTML tag.
- The `name` is the path under the islands folder without extension, and is case-sensitive on Linux.
- Check the console for `[nite] island <name> failed`.

## Production

### "wwwroot/_nite/manifest.json was not found"

The app runs in production mode without a build. Publish with `-c Release` (which runs `nite build`), or run `nite build`. Check `NiteBuildEnabled` is not `false`, and that `ASPNETCORE_ENVIRONMENT` is what you expect.

### "Island 'x' is not in the Nite build" or "Module 'x' is not in the Nite build"

The build output is older than the code. Rebuild. For `<nite-module>`, add the module to `entries` in `nite.json`.

### Publish fails with "nite: command not found"

The build runs `nite build` with the `nite` tool on the `PATH`. Install the tool on the build machine, or set `NiteCommand` (for example to `dotnet tool run nite`). See [MSBuild properties](https://nitefx.dev/docs/reference/msbuild.md).

### Assets 404 when the app runs under a path base

Production URLs inside JavaScript and CSS assume the site root. See [Limits](https://nitefx.dev/docs/limits.md#hosting).

## Still stuck?

Open an issue on [GitHub](https://github.com/nite-net/nite/issues) with `nite version`, the command or request that fails, and the output with `--verbose` (or `Nite` logging at `Debug`).


<!-- Source: https://nitefx.dev/docs/changelog.html -->

# Changelog

Notable changes, newest first. NiteFx follows semantic versioning; while it is below 1.0, minor versions may change APIs outside the documented surface.

## Unreleased (main)

### Changed

- **Nite is now NiteFx**, short for Nite Framework, and the docs moved to [nitefx.dev](https://nitefx.dev). Old links to `nite-net.github.io` redirect. Nothing in your project changes: the packages, the `Nite` namespace and the `nite` command keep their names.

### Added

- **Code signing policy and privacy policy.** Release binaries will be signed through [SignPath Foundation](https://signpath.org); see the [Code signing policy](https://nitefx.dev/docs/code-signing.md). The [Privacy policy](https://nitefx.dev/docs/privacy.md) lists the only network connections NiteFx makes. It collects no information.

## 0.8.1

### Added

- **`AGENTS.md` in new projects.** `nite init` and the `dotnet new` templates write an `AGENTS.md` for AI coding agents: the commands, the project layout, and the Vite and npm habits that do not apply. ([Working with an AI coding agent](https://nitefx.dev/docs/getting-started.md#working-with-an-ai-coding-agent))
- **Docs for agents.** The site publishes [`llms.txt`](https://nitefx.dev/llms.txt), [`llms-full.txt`](https://nitefx.dev/llms-full.txt) and a Markdown copy of every page.

## 0.8.0

### Added

- **Several single-page apps in one app.** `MapNiteSpa(page, path: "/login")` serves a page under its own path (and its client-side routes), next to a catch-all app; each is an endpoint with its own authorization. ([More than one page](https://nitefx.dev/docs/guides/single-page-apps.md#more-than-one-page))
- **Content Security Policy nonces.** `NiteOptions.CspNonce` gives NiteFx the request's nonce, which it puts on the import map, client config and module scripts it writes, and in development on the dev client, CSS imported from modules and the error overlay. A strict policy without `'unsafe-inline'` then works in both. `NiteHead.ToHtml(nonce)` does the same for hand-written layouts. ([Content Security Policy](https://nitefx.dev/docs/reference/aspnet.md#content-security-policy))
- **Identity sample.** `samples/Nite.Identity`: ASP.NET Core Identity with EF Core and SQLite, two seeded users, a public login app and a protected main app that receives the user's claims through client config. It follows the backend-for-frontend pattern: server-side sessions behind an HttpOnly `__Host-` cookie, antiforgery tokens, a strict nonce-based CSP, rate-limited sign-in with lockout, and a refusal to run outside Development with the published demo passwords.

### Changed

- Pages carrying client config are sent `Cache-Control: private, no-store` instead of `private, no-cache`, so the browser does not keep a signed-in user's page.

## 0.7.0

### Added

- **Client config.** `NiteOptions.ClientConfig` (or `ClientConfigAsync`) hands values from the running server to client code as each page is served: `import { config } from "nite:config"`. Unlike `NITE_PUBLIC_` variables, which are inlined at compile time, they can differ per environment and per request, so one build runs everywhere. `nite init` and the templates add `Client/nite-env.d.ts` to type them. ([Values from the running server](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server))
- **Application Insights guide.** Browser telemetry with the Application Insights SDK: per-environment connection strings through client config, loading the SDK lazily, and one transaction from page load through API calls. The Aspire sample does all of it. ([Application Insights in the browser](https://nitefx.dev/docs/guides/application-insights.md))
- **Telemetry.** OpenTelemetry traces and metrics through an `ActivitySource` and a `Meter` named `Nite` (`NiteTelemetry.SourceName`, `NiteTelemetry.MeterName`): dev server startup, per-request compiles, each stylesheet tool, hot updates, pre-bundling, package installs and production builds. No OpenTelemetry dependency. ([Telemetry, health checks and Aspire](https://nitefx.dev/docs/guides/observability.md))
- **Health check.** `AddHealthChecks().AddNite()` reports a dev server that is still starting or failed to, and a production app missing its build output.
- **Aspire guide and sample.** Running a NiteFx app under Aspire: wiring, hot reload, passing service URLs to client code, and deploying. `samples/Nite.Aspire` has a NiteFx React app and an API service under one AppHost.
- Requests under `/_nite` are named after their route in traces (`GET /_nite/src/{**path}`) instead of a bare `GET`.

### Changed

- The dev server starts its work once the host has started, so OpenTelemetry sees the startup trace.

## 0.6.0

### Added

- **`dotnet new` templates.** The `Nite.Templates` package adds `nite-spa` and `nite-islands` to `dotnet new` and to the new-project dialogs of Visual Studio and Rider. They are the same files `nite init` writes. ([Getting started](https://nitefx.dev/docs/getting-started.md#with-dotnet-new))

### Changed

- **Releases take their version from the tag.** Pushing `v0.6.0` publishes 0.6.0; there is no version to bump in `Directory.Build.props` first. CI builds are prereleases of the next patch after the newest tag. ([Contributing](https://nitefx.dev/docs/contributing.md#continuous-integration-and-releases))

## 0.5.0

### Added

- **Install script warnings.** Packages the registry marks with `hasInstallScript` are reported when they are resolved, with specific messages for well-known ones (`core-js`, `esbuild`, `node-sass`, native addons such as `bcrypt`). ([Install scripts](https://nitefx.dev/docs/guides/packages.md#install-scripts))
- **Continuous integration and NuGet releases.** A GitHub Actions workflow builds, tests and packs `Nite` and `Nite.Cli` on every push, and publishes them to nuget.org with trusted publishing (no stored API key) when a `v*` tag matching `Version` in `Directory.Build.props` is pushed. ([Contributing](https://nitefx.dev/docs/contributing.md#continuous-integration-and-releases))

## 0.4.0

### Added

- `nite watch --no-auto-restart`.

### Changed

- `nite watch` sets `DOTNET_WATCH_RESTART_ON_RUDE_EDIT=1`, so edits that need a restart (such as a new endpoint in `Program.cs`'s top-level code) restart the app instead of being applied as a no-op that waits for Ctrl+R.
- Production builds add Vite's default browser targets when `target` names only a language version, so CSS nesting and other new syntax are lowered.

## 0.3.0

### Added

- **Stylesheets.** Sass (the native Dart Sass compiler, over its embedded protocol), Less, Tailwind CSS 4 and the project's PostCSS config, in development and production, in the same order as Vite. CSS modules (`*.module.css`, `.module.scss`, `.module.less`) with `composes` and named exports. Package stylesheets imported from code (`import "@mantine/core/styles.css"`), and `url()` assets served in place during development. Hot updates follow everything a stylesheet depends on: imports, Sass partials, the PostCSS config, and new Tailwind classes in any project file, Razor views included. [Mantine](https://nitefx.dev/docs/guides/mantine.md) works out of the box. ([Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md))
- **esbuild plugins in .NET.** The esbuild client implements esbuild's plugin protocol (`onResolve`, `onLoad`), so builds can call back into C#.
- **Importing projects.** `nite init --from` imports Vite and Create React App projects managed by npm, Yarn (classic and Berry), pnpm or Bun, keeping the versions their lockfiles pin, and reports what it could not bring along. Stylesheet tooling and `additionalData` are carried over. ([Importing](https://nitefx.dev/docs/guides/importing.md))
- **Per-user directories and settings.** Configuration and caches follow the XDG Base Directory spec (`~/.config/nite`, `~/.cache/nite`). Layered settings from `NITE_REGISTRY`, `nite.json`, project and user `.npmrc`, and a user config edited with `nite config`. ([Settings](https://nitefx.dev/docs/reference/settings.md))
- **Private registries.** Per-scope registries and `.npmrc` credentials (`_authToken`, `_auth`, `username`/`_password`, with `${VAR}` expansion), sent only to their own host. Registry metadata is cached and revalidated with ETags.
- `nite cache dir|clean|verify` and `nite config list|get|set|unset|path`.

### Fixed

- Version ranges whose alternatives include a dist-tag (`>=3.0.0 || >=4.0.0 || insiders`) no longer fail to install.

## 0.2.0

### Added

- **A new `nite` CLI** built on Spectre.Console: `init` (with `spa` and `islands` templates), `install` (`add`, `i`), `remove` (`rm`, `delete`, `uninstall`), `list` (`ls`), `update` (`up`, with `--check` and `--latest`), `build`, `watch`, `version` and `update-self`.
- `nite watch` runs `dotnet watch` with its browser refresh turned off, so single-page apps keep their state on C# changes; `--browser-refresh` keeps it for Razor Pages.
- The project logo and icon, used for the NuGet packages.

### Changed

- Licensed under the Apache License 2.0.

## 0.1.0

The first version.

- A development server inside ASP.NET Core (`UseNite`): TypeScript and JSX compiled on request by a long-lived esbuild service, bare imports through an import map to pre-bundled dependencies, and hot updates over a WebSocket.
- React Fast Refresh without Babel, driven by a module graph.
- C# hot reload forwarded to the page as a `nite:server-update` event.
- Single-page apps with `index.html` as an entry and `MapNiteSpa` for client-side routing.
- React islands in Razor Pages and MVC: `<island>`, `<nite-head>` and `<nite-module>`, with `load`, `idle`, `visible` and `media` loading strategies.
- An npm client in C#: semver resolution, hoisting, `nite.lock.json`, integrity checks.
- Production builds into `wwwroot/_nite` (minified, code-split, content-hashed), run automatically by `dotnet publish`.
- Environment variables from `.env` files with a public prefix, and tsconfig path aliases.


<!-- Source: https://nitefx.dev/docs/guides/single-page-apps.html -->

# Single-page apps

A single-page app is `Client/index.html`, the modules it loads, and `app.MapNiteSpa()` to serve it. Your API lives in the same app, on the same origin.

## The setup

```csharp
using Nite;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddNite();

var app = builder.Build();
app.UseNite();                       // dev server under /_nite; does nothing in production

app.MapGet("/api/todos", ...);       // your API

app.MapStaticAssets();               // wwwroot, including the production build
app.MapNiteSpa();                    // index.html for "/" and client-side routes
app.Run();
```

Order matters in one place: `UseNite()` must come before anything that would answer `/_nite/...` requests. Calling it right after `builder.Build()` is always safe.

## index.html is the entry

As in Vite, the HTML page is a real entry point, not a template that a bundler injects into:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My app</title>
    <link rel="icon" href="/favicon.ico" />
    <link rel="stylesheet" href="./styles.css" />
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./main.tsx"></script>
  </body>
</html>
```

NiteFx looks at two kinds of tags and leaves everything else alone:

| Tag | Development | Production |
|---|---|---|
| `<script type="module" src="...">` pointing into the client root | Served from `/_nite/src/...`, compiled on request | Replaced by the hashed bundle, its CSS `<link>`s and `modulepreload` hints for its chunks |
| `<link rel="stylesheet" href="...">` pointing into the client root | Served through the [stylesheet pipeline](https://nitefx.dev/docs/guides/stylesheets.md) | Replaced by the hashed, minified CSS |

URLs can be relative to the page (`./main.tsx`) or root-relative (`/src/main.tsx`, resolved against the client root, as Vite does). External URLs (`https://...`, `//cdn...`, `data:`), and local URLs that do not point to a file in the client root, are left exactly as written. That is how you reference static files in `wwwroot`: `<link rel="icon" href="/favicon.ico" />` keeps pointing at `wwwroot/favicon.ico`.

In development the page gets NiteFx's head injected first: the import map for dependencies, the dev client, and the Fast Refresh runtime. In production it gets nothing extra.

> [!NOTE]
> `index.html` is read from source on every request in development, so edits show up on the next load. Saving it reloads open pages.

## Client-side routing

`MapNiteSpa()` is a fallback endpoint. It answers `GET` and `HEAD` requests that no other endpoint or static file handled, for any path without a file extension. Deep links such as `/todos/3` therefore load the app, and the client router takes over.

Real endpoints always win, so you never have to order routes around it. Three cases return 404 instead of the page:

- paths under `/api` (change with `apiPrefix`, or pass `null` to disable): a mistyped API call gets a 404 rather than a page of HTML that fails to parse as JSON;
- methods other than `GET` and `HEAD`;
- paths with a file extension (`/missing.png`).

```csharp
app.MapNiteSpa(apiPrefix: "/backend");   // the API lives under /backend instead
app.MapNiteSpa(apiPrefix: null);         // every extension-less GET falls back
```

The page itself is sent with `Cache-Control: no-cache`, because it is what points at the current hashed bundles.

## Calling your API

The app and the API share an origin, so `fetch("/api/todos")` just works: no CORS policy, no dev proxy, no base URL per environment. Cookies and ASP.NET Core authentication work as they do for any same-origin request.

```ts
export async function getTodos(): Promise<Todo[]> {
  const response = await fetch("/api/todos");
  if (!response.ok) throw new Error(`GET /api/todos failed: ${response.status}`);
  return response.json();
}
```

Re-fetch when C# changes during development with the [`nite:server-update`](https://nitefx.dev/docs/guides/hot-reload.md#c-changes) event.

## More than one page

An `index.html` in the client root is picked up automatically. Other HTML pages are entries too when you list them in `nite.json`:

```json
{
  "entries": ["login/index.html"]
}
```

Give each its own path with `MapNiteSpa`'s `path`: that page answers the path and everything under it, with its own client-side routes, and the more specific path wins over the catch-all.

```csharp
app.MapNiteSpa("login/index.html", path: "/login").AllowAnonymous(); // /login, /login/forgot, ...
app.MapNiteSpa();                                                    // everything else: index.html
```

Each is an ordinary endpoint, so authorization conventions apply per app. Both get [client config](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server) and the same caching headers. The apps share chunks in production builds, so a second app costs only its own code. [`samples/Nite.Identity`](https://github.com/nite-net/nite/tree/main/samples/Nite.Identity) has a public login app and a protected main app.

For full control, [Nite.Assets.INiteAssets](https://nitefx.dev/api/Nite.Assets.INiteAssets.html) returns any page as it should be served in the current mode: `await assets.GetHtmlAsync("admin.html", context)`.

## Hosting under a path base

When the app runs under a path base (`app.UsePathBase("/shop")`, or a reverse proxy that sets one), `MapNiteSpa` adds the path base to the URLs in the page it serves, and the dev server works under it. Production URLs inside JavaScript and CSS (dynamic imports, `url()` assets) are root-relative to `/_nite/`; see [Limits](https://nitefx.dev/docs/limits.md).

## Using another framework

Nothing about the SPA setup is React-specific. `main.ts` can render with plain DOM APIs, Preact (`"jsxImportSource": "preact"`), Lit or anything else that ships ES modules. React Fast Refresh only applies to React; other code reloads the page when it changes.

## See also

- [Tutorial: a full-stack app](https://nitefx.dev/docs/tutorial.md)
- [ASP.NET Core integration](https://nitefx.dev/docs/reference/aspnet.md) for every option of `AddNite`, `UseNite` and `MapNiteSpa`
- [Production builds and deployment](https://nitefx.dev/docs/guides/deployment.md)


<!-- Source: https://nitefx.dev/docs/guides/islands.html -->

# Islands in Razor Pages

Keep your pages server-rendered with Razor, and make the parts that need it interactive with React. Each island is a component, loaded only when it is needed, with props straight from your page model.

```cshtml
<island name="Counter" props="new { start = 5 }" />
```

## Set up

Starting fresh, `nite init my-site --template islands` creates all of this. To add islands to an existing Razor Pages or MVC app:

**1. Register NiteFx** in `Program.cs`:

```csharp
builder.Services.AddRazorPages();
builder.Services.AddNite();

var app = builder.Build();
app.UseNite();          // before routing and static assets
app.UseRouting();
app.MapStaticAssets();
app.MapRazorPages().WithStaticAssets();
```

**2. Import the tag helpers** in `Pages/_ViewImports.cshtml` (or `Views/_ViewImports.cshtml`):

```cshtml
@addTagHelper *, Nite
```

**3. Add `<nite-head />` to your layout's `<head>`.** It emits the island loader, and in development the import map, the dev client and the Fast Refresh runtime:

```cshtml
<head>
    <meta charset="utf-8" />
    <title>@ViewData["Title"]</title>
    <link rel="stylesheet" href="~/site.css" asp-append-version="true" />
    <nite-head />
</head>
```

**4. Add a `nite.json`** next to the project file, with React:

```json
{
  "clientRoot": "Client",
  "islands": "islands",
  "dependencies": { "react": "^19.3.1", "react-dom": "^19.3.1" },
  "devDependencies": { "@types/react": "^19.2.0", "@types/react-dom": "^19.2.0" }
}
```

Then `nite install`.

## Write an island

Any module in `Client/islands/` is an island. Its default export is the component:

```tsx
// Client/islands/Counter.tsx
import { useState } from "react";

export default function Counter({ start }: { start: number }) {
  const [count, setCount] = useState(start);
  return <button onClick={() => setCount(count + 1)}>Clicked {count} times</button>;
}
```

Place it in any page or view:

```cshtml
<island name="Counter" props="new { start = 5 }" />
```

Islands are found by path, without the extension: `Client/islands/admin/UserTable.tsx` is `<island name="admin/UserTable" />`. Code that islands share (hooks, API clients, components that are never islands themselves) belongs outside the islands folder, in `Client/lib/` or wherever you like.

## Props

`props` takes any object. It is serialized to JSON with **camelCase** names (the same convention as ASP.NET Core's JSON APIs) and passed to the component:

```cshtml
<island name="TodoList" props='new { title = "Today", items = Model.Todos }' />
```

```tsx
type Props = { title: string; items: { id: number; title: string; done: boolean }[] };

export default function TodoList({ title, items }: Props) { /* ... */ }
```

Props are plain data: strings, numbers, booleans, arrays, objects, `null`. They are embedded in the page as a `data-props` attribute, so do not pass anything you would not put in the HTML.

> [!TIP]
> Razor attribute values use C# syntax inside `props="..."`. When the object contains string literals, wrap the attribute in single quotes: `props='new { title = "Today" }'`.

## When islands load

By default an island loads as soon as the page does. The `client` attribute defers it:

| `client=` | Loads | Good for |
|---|---|---|
| `load` (default) | Immediately | Above-the-fold interactivity |
| `idle` | When the browser is idle (`requestIdleCallback`, at most 2 seconds later) | Secondary widgets |
| `visible` | When the element comes within 200 px of the viewport | Charts, comments, anything below the fold |
| `media` | When the media query in `media` matches | Components that only exist at some screen sizes |

```cshtml
<island name="Chart" props="Model.Series" client="visible" />
<island name="Sidebar" client="media" media="(min-width: 900px)" />
```

Nothing is downloaded for an island until its strategy fires: not the module, not its dependencies.

## Fallback content

Content inside the tag is rendered by the server and shown until the island mounts, then replaced:

```cshtml
<island name="TodoList" props='new { items = Model.Todos }' client="visible">
    <ul>
        @foreach (var todo in Model.Todos)
        {
            <li>@todo.Title</li>
        }
    </ul>
</island>
```

Use it as a loading state, or as real content for crawlers and users without JavaScript. Islands render on the client only; NiteFx does not server-render React.

## Other options

| Attribute | Default | Meaning |
|---|---|---|
| `name` | (required) | The module's path under the islands folder, without extension. |
| `props` | none | Props, serialized as camelCase JSON. |
| `client` | `load` | When to load; see above. |
| `media` | `all` | The media query for `client="media"`. |
| `export` | `default` | A named export to render instead of the default one: `export="UserTable"`. |
| `tag` | `div` | The wrapper element: `tag="section"`, `tag="span"`. |

The full reference is on [Tag helpers](https://nitefx.dev/docs/reference/tag-helpers.md).

## Islands and dynamic HTML

The island loader watches the document with a `MutationObserver`. Islands added later, by htmx, Turbo, Blazor's enhanced navigation or your own `innerHTML`, mount automatically, and islands that are removed are unmounted (React roots are cleaned up). There is nothing to call.

The observer watches the document, not shadow roots: an island rendered inside a web component's shadow DOM is not found.

## Sharing state between islands

Each island is its own React root, so React context does not cross between them. Share state through a module both import (a small store, a signal, an event bus), or through the server:

```ts
// Client/lib/cart.ts: one module instance per page, shared by every island that imports it
import { useSyncExternalStore } from "react";

let count = 0;
const listeners = new Set<() => void>();

export const cart = {
  add() { count++; listeners.forEach((l) => l()); },
  subscribe(l: () => void) { listeners.add(l); return () => listeners.delete(l); },
};

export const useCartCount = () => useSyncExternalStore(cart.subscribe, () => count);
```

## Styles

Islands can import CSS, CSS modules, Sass and so on, exactly like any other module. In production, the tag helper emits a `<link rel="stylesheet">` for each island's CSS right before the island (once per page), so it never flashes unstyled. In development each import injects its own `<style>` element.

## Modules that are not islands

For a script that should run on a page without being a component (analytics, a page-specific enhancement), use `<nite-module>`:

```cshtml
<nite-module src="pages/checkout.ts" />
```

`src` is relative to the client root. List the module in `entries` in `nite.json` so the production build includes it; in development NiteFx logs a warning when you forget.

```json
{ "entries": ["pages/checkout.ts"] }
```

## Hot reload

Under `nite watch --browser-refresh`, island components update in place with Fast Refresh like any other React component, and Razor changes reload the page through `dotnet watch`. See [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md#razor-pages).

## Not using React

Islands are rendered by a small renderer module. Preact, Solid or plain DOM code work with a custom one; see [Custom renderers](https://nitefx.dev/docs/guides/renderers.md).


<!-- Source: https://nitefx.dev/docs/guides/hot-reload.html -->

# Hot reload and nite watch

`nite watch` runs `dotnet watch` for the C# side while NiteFx handles the client side. Most edits land in the page in a fraction of a second without losing state.

## Start it

```bash
nite watch                      # single-page apps
nite watch --browser-refresh    # Razor Pages and MVC
```

Arguments after `--` go to `dotnet watch`:

```bash
nite watch -- --launch-profile https
nite watch -- --project src/Web/Web.csproj
```

You can also run the app any other way (`dotnet run`, Visual Studio, Rider). The client side still hot-updates; only C# changes need `dotnet watch` (or your IDE's hot reload) to apply.

## What happens when you save

| You edit | What happens | State |
|---|---|---|
| A React component | Fast Refresh updates it in place, in about 100 to 200 ms | Kept |
| A helper module (`format.ts`, `api.ts`) | The components that import it, directly or not, refresh | Kept |
| A component, adding or removing a hook | The component remounts | That component's state resets |
| A stylesheet, or a Sass partial, Less import or PostCSS config it uses | Swapped in place | Kept |
| A CSS module | The components using it refresh | Kept |
| A component using a new Tailwind class (or a Razor view) | The Tailwind stylesheet is rebuilt and swapped in | Kept |
| The entry module (`main.tsx`) or `index.html` | Page reloads | Lost |
| `nite.json` | Packages install, dependencies re-bundle, page reloads | Lost |
| `.env*` or `tsconfig*.json` | Modules recompile, page reloads | Lost |
| C# that hot reload can apply | Applied in the running app; the page gets `nite:server-update` | Kept |
| C# that needs a restart | The app restarts; the page waits and reloads (about 10 s) | Lost |

## Compile errors

A syntax or type-stripping error shows an overlay with the file, line and the offending code, without reloading the page. The page underneath keeps running. Fix the file and the overlay closes on its own; click outside the message to dismiss it early. Stylesheet errors (Sass, Less, PostCSS, Tailwind) show the same way, with line numbers in your source file.

Errors are only shown in development. A production build with an error fails with the same message on the command line.

## How Fast Refresh decides

NiteFx keeps a graph of which modules import which, limited to modules the browser has actually loaded. On a change, it walks up from the changed file:

- a module whose exports are **all React components** is a *boundary*: it is re-imported, and React swaps the new components in, keeping state;
- any other module passes the update to the modules that import it;
- if the walk reaches a module nothing imports (the page's entry), the page reloads.

Things that keep a module from being a boundary, so edits to it propagate further up or reload:

- exporting non-components next to components (`export const routes = [...]` in the same file as `export function App()`);
- class components and higher-order components other than `memo` and `forwardRef`.

Keep components in their own modules and Fast Refresh does the right thing.

> [!NOTE]
> Hook signatures cover a component's own hook calls. If a *custom* hook changes the order of hooks it calls internally, the next render may warn about hook order; save again or reload.

## C# changes

NiteFx registers a hot reload handler in your app. When `dotnet watch` applies a C# change, NiteFx sends the page a `server-update` message, and the dev client dispatches a `nite:server-update` event on `window`. Re-fetch on it:

```ts
export function onServerUpdate(callback: () => void) {
  addEventListener("nite:server-update", callback);
  return () => removeEventListener("nite:server-update", callback);
}

useEffect(() => {
  load();
  return onServerUpdate(load);   // edit the endpoint in C#, see the new data, keep your state
}, []);
```

`event.detail.types` lists the full names of the types that changed, if you want to be selective. The event never fires in production.

### Changes that need a restart

Some C# edits cannot be applied to a running app: a new endpoint in `Program.cs`'s top-level code (that code already ran), a new service registration, a changed method signature. `nite watch` sets `DOTNET_WATCH_RESTART_ON_RUDE_EDIT=1`, so `dotnet watch` restarts the app instead of asking. The dev client notices the socket drop, waits until the server answers again, and reloads.

> [!IMPORTANT]
> Without that variable, an interactive `dotnet watch` treats some of these edits as warnings (`ENC0118: Changing 'top-level code' might not have any effect until the application is restarted`), applies an update that changes nothing, and waits for Ctrl+R. The page then calls an endpoint that does not exist yet. If you run plain `dotnet watch`, set the variable yourself.

To keep `dotnet watch`'s prompt instead, run `nite watch --no-auto-restart`. A value you have already set for the variable is left alone.

## Why nite watch turns off dotnet watch's browser refresh

Plain `dotnet watch` injects a script into HTML responses that reloads the page after **every** C# change, even one hot reload applied. In a single-page app that throws away client state for an API-only change. `nite watch` sets `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH=1` (which only works from the environment, not from `launchSettings.json`), and NiteFx's own client takes over: it reloads after restarts by itself and leaves the page alone otherwise.

## Razor Pages

For Razor Pages and MVC, server-rendered markup changes do need a reload to show. Keep `dotnet watch`'s refresh:

```bash
nite watch --browser-refresh
```

`.cshtml` edits then reload the page through `dotnet watch`, while island components still update in place through Fast Refresh.

## Variables nite watch sets

| Variable | Value | Unless |
|---|---|---|
| `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH` | `1` | `--browser-refresh`, or you set it |
| `DOTNET_WATCH_RESTART_ON_RUDE_EDIT` | `1` | `--no-auto-restart`, or you set it |

`nite watch` prints the command and the variables it set when it starts.

## Troubleshooting

- **Edits do nothing.** Check that the file is under the client root and that the page actually loads it. Changes to files nothing on the page imports are ignored on purpose.
- **The page reloads on every component edit.** The module probably exports something besides components, or is imported by the entry module directly; see [How Fast Refresh decides](https://nitefx.dev/docs/guides/hot-reload.md#how-fast-refresh-decides). Check also that `fastRefresh` is not `false` in `nite.json` and that React is a dependency.
- **Saving in a particular editor misses changes.** Editors that save through a temporary file and a rename are handled; if yours does something unusual, add the folder to your editor's "safe write" exclusions.

More in [Troubleshooting](https://nitefx.dev/docs/troubleshooting.md).


<!-- Source: https://nitefx.dev/docs/guides/typescript.html -->

# TypeScript and JSX

NiteFx compiles `.ts`, `.tsx`, `.jsx` and `.js` with esbuild. Types are stripped, not checked: your editor checks as you type, and `tsc --noEmit` checks in CI. This is the same model as Vite.

## What gets compiled

| Extension | Treated as |
|---|---|
| `.ts`, `.mts` | TypeScript |
| `.tsx` | TypeScript with JSX |
| `.jsx` | JavaScript with JSX |
| `.js`, `.mjs` | JavaScript (with JSX too when `"jsxInJs": true`, as in Create React App) |
| `.json` | A module whose default export is the parsed JSON |
| `.css`, `.scss`, `.sass`, `.less` | Stylesheets; see [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md) |
| Anything else (`.svg`, `.png`, `.woff2`…) | A module whose default export is the file's URL |

Imports can leave off the extension (`./Button` finds `Button.tsx`), can use the TypeScript convention of importing `.js` for a `.ts` file (`./util.js` finds `util.ts`), and can point at a folder with an `index` file.

## JSX

JSX uses the **automatic runtime** (`react/jsx-runtime`), so components do not need `import React`. Set `jsxImportSource` in `nite.json` to use another library's runtime:

```json
{ "jsxImportSource": "preact" }
```

In development NiteFx uses the dev runtime (`react/jsx-dev-runtime`), which adds component stacks and source locations to React's warnings.

## tsconfig.json

The tsconfig in the client root is for your editor and for `tsc`. NiteFx uses `compilerOptions.paths` and `baseUrl` from it (see [path aliases](https://nitefx.dev/docs/guides/environment.md#path-aliases)); how code is compiled (JSX runtime, target) is set in `nite.json`, not here. The template's config is a good starting point:

```json
{
  // Editor settings only: nite compiles with esbuild, which strips types without
  // checking them. Run `tsc --noEmit` in CI for type checking.
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "react-jsx",
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "skipLibCheck": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "typeRoots": ["../node_modules/@types"]
  },
  "include": ["**/*.ts", "**/*.tsx"]
}
```

Two settings matter more than they look:

- **`isolatedModules: true`** makes the editor flag code that a per-file compiler like esbuild cannot handle, such as re-exporting a type without `export type`.
- **`moduleResolution: "Bundler"`** matches how NiteFx resolves imports: package `exports`, extensionless relative imports and `index` files.

NiteFx follows `extends` and Vite's `references` layout, so a `tsconfig.json` that references `tsconfig.app.json` works.

## Declarations for what NiteFx provides

TypeScript does not know about `import.meta.env`, stylesheet imports or asset URLs until you declare them. Add `Client/nite-env.d.ts` (imported projects get one automatically):

```ts
// What nite provides to client code.
interface ImportMetaEnv {
  readonly MODE: string;
  readonly DEV: boolean;
  readonly PROD: boolean;
  readonly BASE_URL: string;
  readonly SSR: boolean;
  readonly [key: string]: string | boolean | undefined;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

declare module "*.module.css" { const classes: Record<string, string>; export default classes; }
declare module "*.module.scss" { const classes: Record<string, string>; export default classes; }
declare module "*.module.less" { const classes: Record<string, string>; export default classes; }
declare module "*.css";
declare module "*.scss";
declare module "*.less";
declare module "*.svg" { const url: string; export default url; }
declare module "*.png" { const url: string; export default url; }
declare module "*.jpg" { const url: string; export default url; }
declare module "*.webp" { const url: string; export default url; }
declare module "*.woff2" { const url: string; export default url; }

// process.env.NODE_ENV and public variables are inlined at build time.
declare const process: { env: { readonly NODE_ENV: "development" | "production"; readonly [key: string]: string | undefined } };
```

Leave out the `process` declaration if you install `@types/node`, which declares it already. Name your public variables in `ImportMetaEnv` for autocompletion:

```ts
interface ImportMetaEnv {
  readonly NITE_PUBLIC_API_URL: string;
}
```

## Type checking

Install TypeScript as a dev dependency and run its compiler from `node_modules`. NiteFx does not run it for you, the same as Vite.

```bash
nite add -D typescript
```

`tsc` itself is JavaScript, so it needs a JavaScript runtime to run. On a developer machine your editor already runs it. In CI, GitHub's hosted runners (and most others) have Node preinstalled; run the compiler NiteFx installed:

```yaml
# .github/workflows/ci.yml (excerpt)
- run: nite install
- run: node node_modules/typescript/bin/tsc --noEmit -p Client
```

NiteFx does not create `node_modules/.bin` links, so call the package's script directly rather than through `npx` (which would download TypeScript again).

## Targets

- **Development** compiles to ES2022 for any modern browser.
- **Production** uses `"target"` from `nite.json` (default `es2022`), plus Vite's default browser list when the target names only a language version, so newer syntax in JavaScript and CSS is lowered for browsers from the last few years.

```json
{ "target": "es2020,safari15" }
```

See [nite.json](https://nitefx.dev/docs/reference/nite-json.md#target).


<!-- Source: https://nitefx.dev/docs/guides/environment.html -->

# Environment variables and path aliases

Client code reads configuration from `import.meta.env`, filled at compile time from `.env` files and the environment. Only variables with a public prefix ever reach the browser.

## Public variables

Put variables in a `.env` file in the project folder, next to `nite.json`:

```ini
# .env
NITE_PUBLIC_API_URL=/api
NITE_PUBLIC_SENTRY_DSN=https://abc@o1.ingest.sentry.io/1
DATABASE_PASSWORD=hunter2          # never reaches the browser
```

Read them in client code:

```ts
const api = import.meta.env.NITE_PUBLIC_API_URL;       // "/api"
const mode = import.meta.env.MODE;                     // "development" or "production"
if (import.meta.env.DEV) console.debug("debug build");
```

**Only names that start with an `envPrefix`** are exposed. The default prefix is `NITE_PUBLIC_`; everything else in `.env` (database passwords, API keys for the server) stays on the server. Values are inlined into the compiled code as string literals, so they are public in the bundle: never give a secret a public prefix.

## Values from the running server

Public variables are inlined when code is compiled, so a production build carries whatever was set when `nite build` ran. That is wrong for values that differ between environments when the same build is deployed to each (an Application Insights connection string, another service's URL), and impossible for values that differ per request (the signed-in user, a feature flag, a tenant). For those, the server hands values to the page as it serves it:

```csharp
// Program.cs
builder.Services.AddNite(options => options.ClientConfig = context => new
{
    AppInsights = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"],
    User = context.User.Identity?.Name,
    Features = new { NewCheckout = context.User.IsInRole("beta") },
});
```

```ts
import { config } from "nite:config";

if (config.features.newCheckout) { /* ... */ }
```

How it works:

- The callback runs for each page `MapNiteSpa` serves and each page with `<nite-head />`. The result is serialized as camelCase JSON into a `<script type="application/json" id="nite-config">` element at the top of `<head>`; `nite:config` parses it once and exports it frozen. There is no extra request.
- It works the same in development and production, and the same build runs in every environment.
- For values that take awaiting (a database, `IFeatureManager`), set `ClientConfigAsync = async context => new { ... }` instead.
- Pages that carry client config are sent with `Cache-Control: private, no-store`, so a shared cache or CDN never hands one user's page to another, and the browser does not keep a signed-in user's page after they sign out.

Everything in it is readable by anyone who can load the page, like the rest of the HTML: send what the page needs, never secrets. (An Application Insights connection string is fine: the browser SDK needs it anyway.) The JSON is escaped so values cannot break out of the script element.

### Typing it

`nite init` and the `dotnet new` templates create `Client/nite-env.d.ts`. Describe what your callback returns there:

```ts
declare module "nite:config" {
  export interface NiteClientConfig {
    appInsights?: string;
    user?: string;
    features: { newCheckout: boolean };
  }

  export const config: Readonly<NiteClientConfig>;
  export default config;
}
```

### Client config, cookies or an API call?

| | Client config | A cookie | An API call |
|---|---|---|---|
| Arrives | With the page | With the page, and on every later request | After the page has loaded |
| Size | As big as the page can bear | About 4 KB | Any |
| Readable by scripts | Yes | Only if not `HttpOnly` | Yes |
| Changes during the visit | No | Yes | Yes |

Use client config for what the page needs to start: settings, who the user is, flags. Keep authentication in an `HttpOnly` cookie, which scripts cannot read and the browser sends for you. Fetch anything that changes while the page is open.

## Built-in values

| Expression | Development | Production |
|---|---|---|
| `import.meta.env.MODE` | `"development"` | `"production"` |
| `import.meta.env.DEV` | `true` | `false` |
| `import.meta.env.PROD` | `false` | `true` |
| `import.meta.env.BASE_URL` | `"/"` | `"/"` |
| `import.meta.env.SSR` | `false` | `false` |
| `process.env.NODE_ENV` | `"development"` | `"production"` |

These match Vite, so code and libraries written for Vite work unchanged. Public variables are also available as `process.env.NAME`, the Create React App convention, and `process.env.PUBLIC_URL` is `""` when the `REACT_APP_` prefix is in use.

## Files and precedence

Files are read from the project folder, later ones overriding earlier ones:

1. `.env`
2. `.env.local`
3. `.env.development` or `.env.production` (by mode)
4. `.env.development.local` or `.env.production.local`

**Variables already set in the process environment win over all files**, so CI can override a committed `.env` without editing it:

```bash
NITE_PUBLIC_API_URL=https://api.example.com dotnet publish -c Release
```

Commit `.env` and `.env.development` / `.env.production` with non-secret defaults. Keep `.env*.local` out of git (the generated `.gitignore` already does) for per-machine values.

### Syntax

```ini
# Comments start with #
NITE_PUBLIC_A=plain value
NITE_PUBLIC_B="double quoted, with \n newlines"
NITE_PUBLIC_C='single quoted, taken literally'
export NITE_PUBLIC_D=works too       # inline comments after an unquoted value
```

## Changing the prefix

```json
{ "envPrefix": ["VITE_", "NITE_PUBLIC_"] }
```

Projects imported from Vite get `["VITE_"]` (or whatever `envPrefix` the Vite config set), and Create React App projects get `["REACT_APP_"]`, so their code keeps working.

## Reloading

Editing a `.env` file while the app runs recompiles the client and reloads the page with the new values. In production, values are fixed at build time: change them and rebuild.

> [!NOTE]
> These are build-time values for the client. For runtime configuration that differs between environments without a rebuild, serve it from your API (`/api/config`) and fetch it on startup.

## Types

Declare your variables for autocompletion and type checking in `Client/nite-env.d.ts` (see [TypeScript](https://nitefx.dev/docs/guides/typescript.md#declarations-for-what-nitefx-provides)):

```ts
interface ImportMetaEnv {
  readonly NITE_PUBLIC_API_URL: string;
  readonly NITE_PUBLIC_SENTRY_DSN?: string;
}
```

## Path aliases

Aliases from `compilerOptions.paths` in the client's tsconfig work in development and production, so imports resolve exactly as they do in your editor:

```json
// Client/tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@ui": ["./src/components/index.ts"]
    }
  }
}
```

```ts
import { cn } from "@/lib/utils";
import { Button } from "@ui";
```

NiteFx follows `extends` (relative files) and Vite's `references` layout, where paths usually live in `tsconfig.app.json`. Aliases can point at code, stylesheets and assets alike. A `baseUrl` also makes a non-relative import resolve against it when a matching file exists there (`import "lib/utils"` finds `Client/lib/utils.ts` with `"baseUrl": "."`), as in TypeScript.

Editing a tsconfig while the app runs recompiles everything and reloads the page, since any import could now resolve differently.

> [!TIP]
> Vite projects sometimes define aliases in `vite.config` (`resolve.alias`) instead. NiteFx reads only tsconfig, which your editor needs anyway; move them there. The importer warns when it sees this.


<!-- Source: https://nitefx.dev/docs/guides/renderers.html -->

# Custom renderers

Islands are mounted by a renderer: a module with one function. NiteFx ships one for React; point `"renderer"` at your own to use something else.

## The contract

A renderer is a module in the client root that exports `mount`:

```ts
export function mount(
  element: HTMLElement,   // the island's wrapper element
  component: unknown,     // the island module's export (default, or the one named by export="…")
  props: object,          // the props from the tag helper, parsed from JSON
): void | (() => void) | Promise<void | (() => void)>;
```

Return a function to clean up when the island's element is removed from the page; the loader calls it then. The built-in React renderer is the whole reference implementation:

```js
import { createElement } from "react";
import { createRoot } from "react-dom/client";

export function mount(el, Component, props) {
  const root = createRoot(el);
  root.render(createElement(Component, props));
  return () => root.unmount();
}
```

Register yours in `nite.json`, relative to the client root:

```json
{ "renderer": "renderer.ts" }
```

## Preact

```bash
nite rm react react-dom @types/react @types/react-dom
nite add preact
```

```json
{
  "jsxImportSource": "preact",
  "renderer": "renderer.ts"
}
```

```ts
// Client/renderer.ts
import { h, render, type ComponentType } from "preact";

export function mount(el: HTMLElement, Component: ComponentType<any>, props: object) {
  el.replaceChildren();                       // drop the server-rendered fallback
  render(h(Component, props), el);
  return () => render(null, el);
}
```

Islands are now Preact components with the same `<island>` tag helper. Set `"jsxImportSource": "preact"` in your tsconfig too (`"jsx": "react-jsx"`, `"jsxImportSource": "preact"`) for the editor.

## Plain DOM

Islands do not have to be components at all. With this renderer, an island module's default export is a function that receives the element and props:

```ts
// Client/renderer.ts
type Island = (el: HTMLElement, props: object) => void | (() => void);

export function mount(el: HTMLElement, island: Island, props: object) {
  return island(el, props);
}
```

```ts
// Client/islands/Clock.ts
export default function Clock(el: HTMLElement, { zone }: { zone: string }) {
  const tick = () => (el.textContent = new Date().toLocaleTimeString("en", { timeZone: zone }));
  tick();
  const timer = setInterval(tick, 1000);
  return () => clearInterval(timer);
}
```

```cshtml
<island name="Clock" props='new { zone = "Europe/Oslo" }' tag="span" />
```

## Hot reload with other renderers

React Fast Refresh only applies when `jsxImportSource` is `react` and React is a dependency. With another renderer, edits to island modules reload the page; stylesheets still swap in place.


<!-- Source: https://nitefx.dev/docs/guides/packages.html -->

# Packages and the lockfile

NiteFx installs packages from the npm registry into an ordinary `node_modules` folder, with a small npm client written in C#. You manage them with `nite add`, `nite rm` and `nite update`; there is no `package.json`.

## Dependencies live in nite.json

```json
{
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1",
    "react-router": "^8.5.0"
  },
  "devDependencies": {
    "@types/react": "^19.2.0",
    "typescript": "~6.0.3"
  }
}
```

- **`dependencies`** are what your client code imports. They are bundled.
- **`devDependencies`** are installed but never bundled: type packages for your editor, TypeScript, and stylesheet tools such as `sass-embedded`, `tailwindcss` and PostCSS plugins (NiteFx runs those itself; see [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md)).

The split only matters for clarity, as with any bundler: what ends up in the bundle is what your code imports.

## Adding packages

```bash
nite add react-router             # latest version, saved as ^8.5.0
nite add react@^19                # a range, saved as written
nite add zod@latest               # a dist-tag, saved as ^<that version>
nite add -D @types/node           # to devDependencies
nite add -E lodash-es             # pin the exact version: 4.17.21, not ^4.17.21
nite add react-router zod clsx    # several at once
```

`nite add` (also `nite install <pkg>` or `nite i <pkg>`) edits `nite.json` (keeping your comments and formatting), resolves, updates `nite.lock.json` and installs. Without arguments, `nite install` installs everything in `nite.json`.

You can also edit `nite.json` by hand. If the app is running in development, the dev server notices, installs, pre-bundles the new packages and reloads the page.

## Removing packages

```bash
nite rm react-router              # also: nite remove, nite delete, nite uninstall
```

Removes the package from `nite.json` and from `node_modules`, along with anything only it depended on.

## Seeing what is installed

```bash
nite list            # direct packages: range and installed version
nite list --all      # every installed package, with where it sits if nested
```

## Updating

```bash
nite update --check       # report current, wanted and latest; change nothing
nite update               # move everything to the newest version its range allows
nite update react         # just these packages
nite update --latest      # move ranges to the latest versions, across majors too
```

*Wanted* is the newest version the range in `nite.json` allows; *latest* is the registry's `latest` tag. `--latest` rewrites the range, keeping its style: `^18.3.1` becomes `^19.3.1`, an exact `4.17.20` becomes `4.17.21`.

## The lockfile

`nite.lock.json` records the exact version, tarball URL and integrity hash of every installed package, and where in `node_modules` it goes. **Commit it.** It is what makes installs repeatable:

- With a lockfile that matches `nite.json`, an install does not ask the registry for metadata at all; it only downloads tarballs it does not have cached.
- Adding a package keeps every other package at its locked version unless a range forces a change. Adding one package never quietly upgrades the rest; that is what `nite update` is for.
- Editing a range in `nite.json` re-resolves, preferring locked versions wherever they still fit.

Do not edit the lockfile by hand. If it gets into a bad state (a merge conflict, say), delete it and run `nite install`: versions are re-resolved from the ranges.

## How resolution works

| Feature | Supported |
|---|---|
| Semver ranges: `^1.2.3`, `~1.2`, `>=1 <2`, `1.x`, `1.2.3 - 1.4`, `||` | Yes |
| Dist-tags: `latest`, `next`, and tags inside ranges (`>=4 \|\| next`) | Yes |
| Exact versions and prereleases (`1.0.0-beta.2`) | Yes |
| Scoped packages (`@scope/name`) and per-scope registries | Yes |
| Peer dependencies | Installed when missing, like npm 7+ (optional peers skipped) |
| Hoisting | Top level unless it would conflict, otherwise nested under the dependent |
| `git:`, `file:`, `link:`, `workspace:`, URL and `npm:` alias dependencies | No |
| Optional dependencies | Skipped |
| Install scripts (`preinstall`, `postinstall`) | **Never run**, with a warning ([below](https://nitefx.dev/docs/guides/packages.md#install-scripts)) |

Not running install scripts is deliberate: it removes a common supply-chain attack path and the need for a JavaScript runtime. The cost is that packages that build native addons or download binaries in `postinstall` do not work. Packages that ship platform binaries as optional dependencies (esbuild, Sass, lightningcss) are not installed either; NiteFx fetches the esbuild and Sass binaries it needs itself.

### Install scripts

The registry marks every version that has a `preinstall`, `install` or `postinstall` script (or a `binding.gyp`, which implies one) with `hasInstallScript`. When NiteFx resolves such a package, it tells you, once per package and after resolution has finished, so the messages are not buried:

```text
› Resolving 4 package(s) from https://registry.npmjs.org
warn  bcrypt@5.1.1 has an install script, which Nite does not run; it is a native Node.js addon, which cannot run in a browser. Server-side work like this belongs in your ASP.NET Core code.
› core-js@3.51.0 has an install script, which Nite does not run; it only prints a message, so nothing is missing.
› esbuild@0.25.12 has an install script, which Nite does not run; it fetches the esbuild binary, which Nite downloads and runs itself.
```

A short list of well-known packages gets a specific message; scripts known to be harmless to skip are reported as information rather than warnings:

| Package | Level | Why |
|---|---|---|
| `core-js`, `core-js-pure`, `es5-ext` | info | The script only prints a message. Nothing is missing. |
| `esbuild` | info | The script fetches the esbuild binary. NiteFx downloads and runs its own. |
| `node-sass` | warning | The script builds LibSass, a native addon. NiteFx compiles Sass with Dart Sass's native binary; replace `node-sass` with `sass`. |
| `bcrypt`, `better-sqlite3`, `sqlite3`, `argon2`, `canvas` | warning | Native Node.js addons, which cannot run in a browser. That work belongs in your ASP.NET Core code. |
| Anything else | warning | If the package needs its script to download or build something, it may not work. |

The messages appear whenever the lockfile is resolved: `nite add`, `nite update`, or a changed `nite.json`. An install from a current `nite.lock.json` does not resolve anything, so it does not repeat them.

## Integrity and caching

Every tarball is checked against the `integrity` hash the registry published (SHA-512, or SHA-1 for very old packages) before it is extracted. Tarballs and registry metadata are cached per user, in `~/.cache/nite` on Linux and macOS (see [Settings and directories](https://nitefx.dev/docs/reference/settings.md)); metadata is revalidated with its ETag, so resolving an unchanged package costs a `304`.

```bash
nite cache verify    # re-check cached tarballs, drop corrupt ones
nite cache clean     # delete the cache
nite cache dir       # print where it is
```

## Installs and the running app

The dev server installs on startup and whenever `nite.json` changes, and `nite install` can run at the same time: a lock file in `.nite/` makes sure only one of them touches `node_modules` at a time.

## Using packages

Import packages by name, as with any bundler:

```ts
import { useState } from "react";
import { z } from "zod";
import debounce from "lodash-es/debounce";
import "@fontsource/inter/400.css";        // CSS from a package
```

Subpaths go through the package's `exports` field. CommonJS packages work, including named imports (`import { useState } from "react"`, while React is still CommonJS). CSS imported from code goes through the [stylesheet pipeline](https://nitefx.dev/docs/guides/stylesheets.md).

Importing a package that is not in `nite.json` shows an error overlay naming it, so you can `nite add` it.

## Private registries

Scoped registries and credentials come from your existing `.npmrc`. See [Private registries](https://nitefx.dev/docs/guides/private-registries.md).


<!-- Source: https://nitefx.dev/docs/guides/private-registries.html -->

# Private registries

NiteFx reads registries and credentials from the `.npmrc` files you already have. Scoped packages can come from their own registry, and credentials are only ever sent to the host they belong to.

## A scoped registry

The usual setup: your organization publishes `@acme/*` to its own registry, and everything else comes from npmjs.org. Put this in a `.npmrc` next to `nite.json` (or in `~/.npmrc` for all projects):

```ini
@acme:registry=https://npm.acme.dev/
//npm.acme.dev/:_authToken=${ACME_NPM_TOKEN}
```

`${ACME_NPM_TOKEN}` is expanded from the environment, so the token itself stays out of the file and out of git. Then:

```bash
export ACME_NPM_TOKEN=...      # or set it in your shell profile, or CI secrets
nite add @acme/design-system
```

## A mirror or proxy for everything

To send all requests to a mirror (Artifactory, Verdaccio, a corporate proxy):

```ini
registry=https://artifacts.acme.dev/api/npm/npm/
//artifacts.acme.dev/api/npm/npm/:_authToken=${ARTIFACTORY_TOKEN}
```

Or without touching `.npmrc`:

```bash
nite config set registry https://artifacts.acme.dev/api/npm/npm/   # this user, every project
NITE_REGISTRY=https://artifacts.acme.dev/api/npm/npm/ nite install   # one command
```

`"registry"` in `nite.json` sets it for one project, for everyone who builds it.

## Credentials

Credentials use npm's "nerf-dart" keys: `//host/path/:` followed by the setting.

| Setting | Meaning |
|---|---|
| `//host/path/:_authToken=TOKEN` | Bearer token (most registries) |
| `//host/path/:_auth=BASE64` | Basic auth, `user:password` already base64-encoded |
| `//host/path/:username=USER` and `//host/path/:_password=BASE64` | Basic auth, password base64-encoded |

A credential is sent **only** to URLs under its host and path. A tarball served from another host (a CDN, say) never receives it. NiteFx refuses to store credentials in its own config: `nite config set` rejects them, and they stay in `.npmrc` where npm, your editor and other tools also find them.

## Where settings come from

Highest first:

1. `NITE_REGISTRY` (environment)
2. `"registry"` in the project's `nite.json`
3. The project's `.npmrc`
4. NiteFx's user config (`nite config set`)
5. The user's `~/.npmrc` (or the file `$NPM_CONFIG_USERCONFIG` names)
6. The default: `https://registry.npmjs.org/`

See exactly what applies, and where each value comes from:

```bash
nite config list --show-origin
```

```text
╭────────────────────────────┬─────────────────────────────┬─────────╮
│ Key                        │ Value                       │ Origin  │
├────────────────────────────┼─────────────────────────────┼─────────┤
│ //npm.acme.dev/:_authToken │ (set)                       │ .npmrc  │
│ @acme:registry             │ https://npm.acme.dev/       │ .npmrc  │
│ init.template              │ spa                         │ default │
│ registry                   │ https://registry.npmjs.org/ │ default │
╰────────────────────────────┴─────────────────────────────┴─────────╯
User config: /home/you/.config/nite/config.json
```

Credentials are never printed: a token shows as `(set)`.

## In CI

Pass the token as a secret environment variable and keep `.npmrc` (with `${VAR}` placeholders) in the repository:

```yaml
- run: nite install
  env:
    ACME_NPM_TOKEN: ${{ secrets.ACME_NPM_TOKEN }}
```

`dotnet publish -c Release` runs `nite build`, which installs first, so the variable has to be set for the publish step too (or run `nite install` in an earlier step with it).

## The esbuild and Sass binaries

NiteFx downloads the esbuild binary (and the Dart Sass binary, if you use Sass) from the npm registry too, through the same settings: a mirror that proxies npmjs.org serves them. Fully offline machines can point NiteFx at binaries they supply instead, with `NITE_ESBUILD_PATH` and `NITE_SASS_PATH`; see [Environment variables](https://nitefx.dev/docs/reference/environment-variables.md).


<!-- Source: https://nitefx.dev/docs/guides/stylesheets.html -->

# Stylesheets

NiteFx processes stylesheets the way Vite does: Sass or Less by extension, then Tailwind, then your PostCSS config, then esbuild for imports, CSS modules and assets. The same pipeline runs in development and in production builds, so the two agree.

## Ways to load CSS

| How | Example | Development | Production |
|---|---|---|---|
| Import from code | `import "./app.css"` | A `<style>` tag, updated in place on save | Extracted into the entry's `.css` file |
| Import a CSS module | `import styles from "./Card.module.css"` | A `<style>` tag plus the class map | Extracted; class names minified |
| Import from a package | `import "@mantine/core/styles.css"` | Served from `node_modules` | Bundled |
| Link from `index.html` | `<link rel="stylesheet" href="./styles.css">` | Served as CSS | Replaced by the hashed file |
| `@import` in CSS | `@import "./theme.css";` | Inlined | Inlined |

Static stylesheets in `wwwroot` (`<link href="~/site.css">` in a Razor layout) are ordinary static files: NiteFx does not touch them.

## The pipeline

Every stylesheet in your client folder goes through these steps, in order:

1. **Sass** for `.scss` and `.sass`, or **Less** for `.less`.
2. **Tailwind CSS 4**, when the file uses it (`@import "tailwindcss"`, `@apply`, `@theme`, `@reference`, `@utility` and friends).
3. **PostCSS**, when the project has a config, with its plugins.
4. **esbuild**: inlines `@import` (packages too, through their `exports` and the `style` condition), scopes CSS modules, resolves `url()` assets, and in production minifies and lowers modern syntax (nesting, for one) for the target browsers.

Each step is optional and only runs when you use it. Plain CSS without a PostCSS config goes straight to esbuild.

## Installing the tools

Install the tools you use as dev dependencies, exactly as you would for Vite. NiteFx runs them; you never need Node:

```bash
nite add -D sass-embedded                  # or: sass
nite add -D less
nite add -D tailwindcss
nite add -D postcss autoprefixer           # plus any PostCSS plugins your config names
```

How each one runs:

| Tool | Runs as |
|---|---|
| **Sass** | The native Dart Sass compiler, from the `sass-embedded-<platform>` npm package matching your `sass` or `sass-embedded` version. Downloaded once into the user cache, like esbuild, and driven over Sass's embedded protocol: one compiler process serves every compile, in tens of milliseconds. |
| **Less**, **PostCSS** (and plugins), **Tailwind** | These are plain JavaScript. NiteFx bundles them from your `node_modules` with esbuild and runs them in [Jint](https://github.com/sebastienros/jint), a JavaScript interpreter written in C#, with a small stand-in for the Node built-ins they use (`fs`, `path`, `url`…). |

The interpreter is slower than Node. The first compile of a Tailwind stylesheet takes a second or two, which the dev server does at startup alongside dependency pre-bundling; after that, updates take tens of milliseconds. A production build pays it once.

> [!NOTE]
> Plugins must be plain JavaScript. A PostCSS or Tailwind plugin that loads a native addon (a `.node` file) cannot run in the interpreter.

## CSS modules

Files named `*.module.css` (or `.module.scss`, `.module.less`) are CSS modules: class names are scoped to the file and imported as an object.

```css
/* Card.module.css */
.card { padding: 1rem; border-radius: 8px; }
.title { composes: heading from "./type.module.css"; font-weight: 700; }
.is-active { outline: 2px solid; }
```

```tsx
import styles from "./Card.module.css";
// or individual names: import { card, title } from "./Card.module.css";

<div className={styles.card}>
  <h2 className={styles.title}>…</h2>
  <div className={styles["is-active"]} />
</div>
```

- `composes` works, within a file and from other modules.
- Named imports work for names that are valid JavaScript identifiers; use the default export for names like `is-active`.
- In development, class names look like `Card_3fa2c1_card` (readable, unique per file); in production they are minified.
- Editing a CSS module refreshes the components that use it, keeping their state.

## Sass

```scss
// Card.module.scss
@use "sass:math";
@use "./tokens" as t;

.card {
  padding: t.$space-3;
  border-radius: math.div(t.$radius, 2);

  &:hover { background: t.$surface-hover; }
}
```

- The client root and `node_modules` are load paths, so `@use "tokens"` finds `Client/_tokens.scss` and `@use "bootstrap/scss/functions"` finds the package.
- `pkg:` URLs work (`@use "pkg:bootstrap"`), resolved through `package.json`.
- Warnings from packages (`quietDeps`) are silenced; your own deprecation warnings appear in the log. Silence specific ones with `silenceDeprecations`.

Options use Vite's names, under `css.preprocessorOptions.scss` in `nite.json`:

```json
{
  "css": {
    "preprocessorOptions": {
      "scss": {
        "additionalData": "@use \"tokens\" as t;",
        "loadPaths": ["shared/styles"],
        "silenceDeprecations": ["import"]
      }
    }
  }
}
```

**`additionalData`** is prepended to every Sass file. It is how a project shares variables and mixins without importing them everywhere. Error line numbers account for it, so they still point at the right line in your file.

## Less

```less
@import "./variables";

.button {
  .rounded(6px);
  color: darken(@brand, 10%);
}
```

The importing file's folder, the client root and `node_modules` are search paths. Options go under `css.preprocessorOptions.less`:

```json
{
  "css": {
    "preprocessorOptions": {
      "less": {
        "additionalData": "@import \"variables\";",
        "paths": ["shared/less"],
        "javascriptEnabled": false,
        "globalVars": { "brand": "#1f74a0" },
        "modifyVars": { "radius": "4px" }
      }
    }
  }
}
```

## PostCSS

NiteFx finds your PostCSS config the way `postcss-load-config` does, in the client root first and then the project folder:

- `postcss.config.js`, `.cjs`, `.mjs`, `.ts`, `.cts`, `.mts`
- `.postcssrc`, `.postcssrc.json`, `.postcssrc.js`, `.postcssrc.cjs`, `.postcssrc.mjs`
- a `"postcss"` field in `package.json`

All the usual forms work: an object of plugin names and options, an array of plugins (`require("autoprefixer")`), and a function of `ctx` (where `ctx.env` is `"development"` or `"production"`).

```js
// postcss.config.cjs
module.exports = {
  plugins: {
    "postcss-preset-mantine": {},
    autoprefixer: {},
  },
};
```

Plugins load from your `node_modules`. `@tailwindcss/postcss` is skipped if listed, because NiteFx runs Tailwind itself, before PostCSS, the same order the plugin would have.

PostCSS runs on your stylesheets only, not on CSS shipped inside packages (that CSS is already built, and re-processing a large framework stylesheet in the interpreter is slow). Turn PostCSS off entirely with:

```json
{ "css": { "postCss": false } }
```

Editing the PostCSS config updates every stylesheet that used it, in place.

## Assets in CSS

`url()` references are resolved like imports:

```css
.hero { background: url("./images/hero.webp"); }        /* relative to this file */
@font-face { src: url("~@fontsource/inter/files/inter-latin-400-normal.woff2"); }  /* a package */
.logo { background: url("/logo.svg"); }                  /* site root: wwwroot, left as is */
```

- In development, relative and package URLs point straight at the files through the dev server.
- In production, they are copied to `wwwroot/_nite/assets/` with a content hash.
- Root-relative URLs (`/logo.svg`), absolute URLs and `data:` URLs are left exactly as written.

> [!NOTE]
> Relative `url()`s inside a Sass partial resolve against the file that uses the partial, not the partial itself (Vite rebases them). Put assets next to the entry stylesheet, or use root-relative or package paths in partials.

## Hot updates

Saving a stylesheet updates it in place, and so does saving anything a stylesheet was built from:

- a file it `@import`s, a Sass partial it `@use`s, a Less import;
- the PostCSS config;
- for Tailwind, any source file that gains a new class name (see [Tailwind CSS](https://nitefx.dev/docs/guides/tailwind.md)).

Errors show in the overlay with the file and line, and clear when you fix them.

## Specific setups

- [Tailwind CSS](https://nitefx.dev/docs/guides/tailwind.md)
- [Mantine](https://nitefx.dev/docs/guides/mantine.md)

## Not supported

- **Stylus.** Convert to CSS, Sass or Less.
- **CSS that a package's own JavaScript imports** (`import "./styles.css"` inside a library). Import the package's stylesheet from your own code instead, as Mantine documents.
- **`css.modules` options** such as `localsConvention` (camelCase class names).


<!-- Source: https://nitefx.dev/docs/guides/tailwind.html -->

# Tailwind CSS

NiteFx runs Tailwind CSS 4 itself: Tailwind's own compiler from your `node_modules`, fed by a class scanner that covers the whole project, Razor views included. No `@tailwindcss/vite`, no `@tailwindcss/postcss`, no CLI process.

## Set up

```bash
nite add -D tailwindcss
```

Import Tailwind in a stylesheet:

```css
/* Client/app.css */
@import "tailwindcss";
```

Load that stylesheet like any other. In a single-page app, import it from the entry module (`import "./app.css"`) or link it from `index.html`. In a Razor site, give the layout a small entry module that imports it:

```ts
// Client/site.ts
import "./app.css";
```

```json
// nite.json
{ "entries": ["site.ts"] }
```

```cshtml
@* Pages/Shared/_Layout.cshtml, in <head> after <nite-head /> *@
<nite-module src="site.ts" />
```

In production `<nite-module>` emits a plain `<link rel="stylesheet">` for the built CSS, so pages render styled from the first paint. Then use classes:

```tsx
export function Card({ title }: { title: string }) {
  return (
    <div className="rounded-xl bg-white p-6 shadow-lg dark:bg-slate-800">
      <h2 className="text-lg font-semibold text-slate-900 dark:text-white">{title}</h2>
    </div>
  );
}
```

```cshtml
<section class="mx-auto max-w-3xl px-4 py-12">
    <h1 class="text-4xl font-bold tracking-tight">@Model.Title</h1>
</section>
```

## Where classes are found

Tailwind generates CSS only for the classes your project uses. Its own scanner is native code, so NiteFx has one written in C# that follows the same rules:

- **Automatic detection** scans the **whole project folder**, not just the client root. Classes used only in `.cshtml` and `.razor` files count.
- Skipped: `node_modules`, `bin`, `obj`, `.git`, `.nite`, `wwwroot/_nite`, folders listed in your `.gitignore` (plain folder names such as `dist/`), lockfiles, stylesheets, and binary files (images, fonts, archives).
- Explicit sources work as documented by Tailwind:

```css
@import "tailwindcss";

@source "../node_modules/@acme/ui/dist";   /* scan a package's compiled components too */
@source not "./legacy";                      /* skip a folder */
@source inline("underline line-through");    /* always generate these */
```

Like Tailwind's own scanner, NiteFx over-collects on purpose: anything that might be a class goes to the compiler, which ignores what is not one. Build class names from complete strings, not concatenation, so they can be found:

```tsx
// Found: both full class names appear in the source.
const color = error ? "text-red-600" : "text-green-600";

// Not found: "text-red-600" never appears anywhere.
const color = `text-${error ? "red" : "green"}-600`;
```

## Theme, utilities and variants

Everything Tailwind 4 does in CSS works, because it is Tailwind's compiler doing it:

```css
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 250);
  --font-display: "Inter", sans-serif;
}

@utility glass {
  backdrop-filter: blur(8px);
  background: rgb(255 255 255 / 0.4);
}

@custom-variant dark (&:where(.dark, .dark *));
```

## Plugins

```bash
nite add -D @tailwindcss/typography @tailwindcss/forms
```

```css
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
```

`@plugin` and `@config` (for a legacy JavaScript config) load from `node_modules` or relative paths. Plugins must be plain JavaScript.

## @apply in CSS modules

To use `@apply` in another stylesheet, reference the main one so Tailwind knows your theme without emitting it twice:

```css
/* Panel.module.css */
@reference "./app.css";

.panel {
  @apply rounded-xl p-6 shadow-lg bg-brand/10;
}
```

## Hot updates

- Saving a component (or a Razor view) that uses a class nothing used before rebuilds the Tailwind stylesheet and swaps it in, without touching component state.
- Saving `app.css` (say, a `@theme` change) updates it, and every stylesheet that `@reference`s it.
- Classes are never forgotten during a session, as with Tailwind's own dev servers, so removing a class does not reorder CSS while you work. The production build only contains classes in use.

The first Tailwind compile in a dev session takes a second or two (Tailwind's compiler runs in a JavaScript interpreter). NiteFx starts it while the app starts, so pages are usually ready by the time you open them.

## Production

`nite build` scans the project, compiles once, and esbuild minifies the result and lowers modern CSS such as nesting for the target browsers. The output is about the same size as a Vite build of the same project (within a few percent in our tests).

## Coming from Vite

`nite init --from` takes care of this, but by hand:

- Remove `@tailwindcss/vite` (and `@tailwindcss/postcss`, if you used PostCSS); keep `tailwindcss` and any plugins.
- Your stylesheet and classes stay exactly as they are.

## Tailwind 3

Tailwind 3 is not supported: its JavaScript configuration and content globs were replaced by CSS-first configuration in version 4, which is what NiteFx runs. Upgrade with Tailwind's tool (`npx @tailwindcss/upgrade`, run once with Node) and the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).


<!-- Source: https://nitefx.dev/docs/guides/mantine.html -->

# Mantine

[Mantine](https://mantine.dev) works in NiteFx the way its Vite guide sets it up: its stylesheet imported from code, `postcss-preset-mantine` for your own CSS modules, and optionally Sass with Mantine's helpers.

## Install

```bash
nite add @mantine/core @mantine/hooks
nite add -D postcss postcss-preset-mantine postcss-simple-vars
```

Add other Mantine packages the same way (`@mantine/dates`, `@mantine/notifications`, …), each with its own stylesheet import.

## PostCSS

Create `Client/postcss.config.cjs`, exactly as in Mantine's guide:

```js
module.exports = {
  plugins: {
    "postcss-preset-mantine": {},
    "postcss-simple-vars": {
      variables: {
        "mantine-breakpoint-xs": "36em",
        "mantine-breakpoint-sm": "48em",
        "mantine-breakpoint-md": "62em",
        "mantine-breakpoint-lg": "75em",
        "mantine-breakpoint-xl": "88em",
      },
    },
  },
};
```

## The provider and styles

Import Mantine's styles once, before your own, and wrap the app in `MantineProvider`:

```tsx
// Client/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "@mantine/core/styles.css";
import { MantineProvider } from "@mantine/core";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <MantineProvider>
      <App />
    </MantineProvider>
  </StrictMode>,
);
```

## Your own styles

CSS modules get everything `postcss-preset-mantine` provides: `rem()` and `em()`, `light-dark()`, `alpha()`, and the `dark`, `light`, `hover`, `rtl` and breakpoint mixins.

```css
/* Client/Card.module.css */
.card {
  padding: rem(20px);
  border: 1px solid light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-4));
  background: alpha(var(--mantine-color-blue-6), 0.1);

  @mixin hover {
    background: alpha(var(--mantine-color-blue-6), 0.2);
  }

  @media (max-width: $mantine-breakpoint-sm) {
    padding: rem(8px);
  }
}
```

```tsx
import { Button, Text } from "@mantine/core";
import classes from "./Card.module.css";

export function Card() {
  return (
    <div className={classes.card}>
      <Text>Hello from Mantine</Text>
      <Button>Click me</Button>
    </div>
  );
}
```

## With Sass

Mantine's Sass guide shares a `_mantine.scss` file of helpers through `additionalData`. Install Sass and put the file in the client root:

```bash
nite add -D sass-embedded
```

```scss
// Client/_mantine.scss
@use "sass:math";

$mantine-breakpoint-md: "62em";

@function rem($value) {
  @return #{math.div(math.div($value, $value * 0 + 1), 16)}rem;
}

@mixin dark {
  [data-mantine-color-scheme="dark"] & {
    @content;
  }
}

@mixin smaller-than($breakpoint) {
  @media (max-width: $breakpoint) {
    @content;
  }
}
```

Then share it with every Sass file. Where Vite's config builds an absolute path, NiteFx only needs the name, because the client root is a Sass load path:

```json
{
  "css": {
    "preprocessorOptions": {
      "scss": { "additionalData": "@use \"mantine\" as mantine;" }
    }
  }
}
```

```scss
// Client/Hero.module.scss
.title {
  font-size: mantine.rem(48px);

  @include mantine.dark {
    color: white;
  }

  @include mantine.smaller-than(mantine.$mantine-breakpoint-md) {
    font-size: mantine.rem(24px);
  }
}
```

PostCSS still runs after Sass, so `light-dark()` and the other preset functions work in `.scss` files too.

## Importing a Mantine Vite app

`nite init my-app --from ../my-mantine-app` carries the whole setup over: the dependencies, `postcss.config.cjs`, and the `additionalData` from `vite.config` (it understands the `path.join(process.cwd(), 'src/_mantine')` form in Mantine's guide). See [Importing a project](https://nitefx.dev/docs/guides/importing.md).

## Notes

- Mantine's own stylesheets (`@mantine/core/styles.css`) are already built, so NiteFx does not run PostCSS over them. That keeps startup fast; the result is identical.
- `@mantine/core/styles.layer.css` (the cascade-layer variant) works the same way.
- Hot updates work for all of it: CSS modules refresh their components with state kept, and editing `_mantine.scss` or `postcss.config.cjs` updates every stylesheet that used it.


<!-- Source: https://nitefx.dev/docs/guides/importing.html -->

# Importing a Vite or Create React App project

`nite init --from` turns an existing npm, Yarn, pnpm or Bun frontend into the client half of a NiteFx project. It keeps the package versions your lockfile pins, carries over the settings it understands, and tells you plainly about the ones it does not.

## Preview, then import

```bash
nite init my-app --from ../vite-app --dry-run   # show the plan, write nothing
nite init my-app --from ../vite-app             # do it
```

The source project is never modified. The new project is a complete ASP.NET Core app (`Program.cs` with `MapNiteSpa`, a sample `/api/hello` endpoint) with your frontend in `Client/`.

## What it supports

| Source | Detected by |
|---|---|
| **Vite** (React) | `index.html` at the project root, plus `vite` in package.json or a `vite.config.*` |
| **Create React App** | `react-scripts` in package.json; `public/index.html` |
| A static `index.html` with modules | `index.html` at the root, no Vite |

| Package manager | Lockfile read |
|---|---|
| npm | `package-lock.json` (v1 to v3), `npm-shrinkwrap.json` |
| Yarn classic | `yarn.lock` v1 |
| Yarn Berry | `yarn.lock` v2+ |
| pnpm | `pnpm-lock.yaml` (v5 to v9) |
| Bun | `bun.lock` (text). The binary `bun.lockb` is not read: run `bun install --save-text-lockfile` first. |

Monorepos (`workspaces`, `pnpm-workspace.yaml`) are refused; import one app at a time with `--from <repo>/packages/<app>`. Next.js, Remix and Astro apps have their own servers and are out of scope.

## What it does

**Files**

- `index.html` and `src/` go to `Client/` (Create React App's `public/index.html` becomes `Client/index.html`, with `%PUBLIC_URL%` removed and the entry script tag CRA used to inject added).
- `public/` goes to `wwwroot/`, where ASP.NET Core serves static files.
- tsconfig files, `postcss.config.*` and `tailwind.config.*` go to `Client/`.
- `.env` files go to the project folder.
- `vite-env.d.ts` / `react-app-env.d.ts` become `nite-env.d.ts` with declarations for what NiteFx provides, and `"types": ["vite/client"]` is dropped from tsconfig (comments in the file survive).

**Packages**

- Runtime `dependencies` are imported, plus any devDependency your source actually imports (bundlers never cared which list a library was in), plus `@types/*` and `typescript`.
- Stylesheet tools are kept as dev dependencies: PostCSS and its plugins, Sass, Less, Tailwind and its plugins.
- Build, lint and test tooling (Vite and its plugins, Babel, ESLint, oxlint, Prettier, Jest, Vitest, Testing Library, …) is skipped: NiteFx replaces the build, and does not run the rest. Imports from test files do not count as runtime imports.
- `@tailwindcss/vite` and `@tailwindcss/postcss` are replaced by `tailwindcss` itself, which NiteFx runs.
- **Versions come from your lockfile.** NiteFx resolves the ranges but prefers the exact versions you run today wherever they still satisfy them, so the imported app runs what it ran before.

**Settings**

- `envPrefix`: `VITE_` for Vite (or the `envPrefix` in `vite.config`), `REACT_APP_` for Create React App.
- `jsxInJs: true` for Create React App, which allows JSX in `.js` files.
- `css.preprocessorOptions.*.additionalData` from `vite.config`, including the path-building template literal in Mantine's Sass guide.

## What it reports

The plan lists everything it could not bring along, so nothing is silently lost:

| Warning | What to do |
|---|---|
| A Vite plugin other than React's and Tailwind's | Nothing replaces it; see whether you still need what it did |
| `resolve.alias` in `vite.config` | Move aliases to tsconfig `paths`, which NiteFx reads |
| `base` in `vite.config` | NiteFx serves from the site root |
| `import.meta.glob`, `?raw`, `?url`, `?worker` imports | Rewrite with explicit imports, `fetch`, or `new Worker(new URL(...))` |
| SVGs imported as React components (svgr) | Import as URLs, or inline the SVG in a component |
| Stylus | Convert to CSS, Sass or Less |
| Tailwind 3 | Upgrade to Tailwind 4 |
| `overrides` / `resolutions` / `pnpm.overrides` | Not supported; versions come from ranges and the lockfile |
| A dependency that is not a registry version (`file:`, `workspace:`, git) | Publish it, or vendor it into `Client/` |
| An imported package package.json does not list | `nite add` it |

It also notes things you no longer need, such as the dev server `proxy` (the app and API now share an origin) and package.json `scripts` (use `nite watch` and `nite build`).

## After importing

```bash
cd my-app
nite watch
```

Then:

1. **Move API calls to relative URLs.** If the app called `http://localhost:5000/api/...` through a proxy, call `/api/...` and implement or proxy those endpoints in `Program.cs`.
2. **Check environment variables.** `import.meta.env.VITE_*` keeps working; values come from the copied `.env` files.
3. **Run your type checker** (`tsc --noEmit`) and tests with the tools you used before; NiteFx does not replace them.
4. **Publish** with `dotnet publish -c Release` and compare the result with your old build.

## Options

| Option | Meaning |
|---|---|
| `--from <path>` | The project to import |
| `--dry-run` | Show the plan; write nothing |
| `--force` | Import into a folder that already has files (existing files are never overwritten) |
| `--no-install` | Write the project without installing packages |
| `--name <name>` | Project name (defaults to the folder name) |
| `--nite-source <path>` | Reference a NiteFx source checkout instead of the NuGet package |
| `--verbose` | Debug output |

See [CLI reference](https://nitefx.dev/docs/reference/cli.md#nite-init).


<!-- Source: https://nitefx.dev/docs/guides/deployment.html -->

# Production builds and deployment

`dotnet publish -c Release` runs `nite build` and includes the result. The published app is an ordinary ASP.NET Core app with static files: no Node, no esbuild, no `node_modules`.

## What publish does

For Release builds, the targets in the `Nite` package run `nite build` before static web assets are collected:

1. `nite build` installs packages from `nite.lock.json` (a no-op when `node_modules` is current);
2. builds every entry (islands, `index.html` and other HTML pages, modules in `entries`) in one esbuild pass: minified, code-split, content-hashed;
3. writes the output and a `manifest.json` to `wwwroot/_nite/`.

The static web assets pipeline then precompresses the files (Brotli and gzip) and `MapStaticAssets` serves them with `ETag`s and the compressed variant each browser accepts. Client sources, `nite.json`, `nite.lock.json`, `node_modules` and `.nite` never reach the publish output.

```bash
dotnet publish -c Release -o publish
```

Run `nite build` on its own to inspect the output without publishing:

```text
$ nite build
╭────────────┬───────────────────────────────────┬───────────┬────────╮
│ Entry      │ Output                            │      Size │ Shared │
├────────────┼───────────────────────────────────┼───────────┼────────┤
│ main.tsx   │ wwwroot/_nite/main-MUGH3OMJ.js    │ 219.2 KiB │      - │
│ styles.css │ wwwroot/_nite/styles-V7BMX6ER.css │   0.3 KiB │      - │
╰────────────┴───────────────────────────────────┴───────────┴────────╯
html  wwwroot/_nite/index.html
✓ Built 2 entries in 176 ms
```

Sizes are before compression; the template's React app is about 60 KB with Brotli.

## Requirements on the build machine

The machine that **builds** needs the .NET SDK and the `nite` tool, plus network access to the npm registry (or your mirror) unless packages and the esbuild binary are already in the user cache. The machine that **runs** the app needs only the ASP.NET Core runtime.

How the build finds the tool is controlled by `NiteCommand`: by default the global `nite`; set it to `dotnet tool run nite` for a [local tool](https://learn.microsoft.com/dotnet/core/tools/local-tools-how-to-use). See [MSBuild properties](https://nitefx.dev/docs/reference/msbuild.md).

## GitHub Actions

```yaml
name: Publish
on:
  push:
    branches: [main]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 10.0.x

      - name: Install nite
        run: dotnet tool install --global Nite.Cli

      # Packages and the esbuild binary are cached per user; keep them between runs.
      - uses: actions/cache@v4
        with:
          path: ~/.cache/nite
          key: nite-${{ runner.os }}-${{ hashFiles('**/nite.lock.json') }}
          restore-keys: nite-${{ runner.os }}-

      - name: Publish
        run: dotnet publish -c Release -o publish

      - uses: actions/upload-artifact@v4
        with:
          name: app
          path: publish
```

## Docker

Build in the SDK image, run in the smaller ASP.NET image:

```dockerfile
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
RUN dotnet tool install --global Nite.Cli
ENV PATH="${PATH}:/root/.dotnet/tools"
WORKDIR /src

# Restore and install packages first, so these layers are cached until dependencies change.
COPY *.csproj nite.json nite.lock.json ./
RUN dotnet restore && nite install

COPY . .
RUN dotnet publish -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
ENTRYPOINT ["dotnet", "MyApp.dll"]
```

Add `node_modules/`, `.nite/`, `bin/`, `obj/` and `wwwroot/_nite/` to `.dockerignore`.

## Caching and CDNs

- Bundles, chunks and assets have content hashes in their names, so a deployment never changes the contents of an existing URL. Today `MapStaticAssets` serves them with `Cache-Control: no-cache` and an `ETag`: browsers revalidate and get a `304` when nothing changed, which is cheap but still a request per file. A CDN rule that caches `/_nite/*` for a long time is safe because of the hashes.
- HTML pages (`MapNiteSpa`'s output, your Razor pages) must not be cached long: they point at the current hashes. `MapNiteSpa` sends `Cache-Control: no-cache`.
- With a long-lived CDN cache, users who still have the previous page open keep loading the previous version's chunks from the CDN. Without one, a lazy-loaded chunk from the old version may be gone after a deployment; a full page load fixes it.

## Path base and subfolders

Production URLs are root-relative under `/_nite/`. `MapNiteSpa` adds the request's path base to the URLs in the page it serves, and the tag helpers do the same, but URLs inside JavaScript and CSS (lazy-loaded chunks, `url()` assets) assume the app is at the site root. Hosting under a subfolder (`/shop`) is therefore limited for now; see [Limits](https://nitefx.dev/docs/limits.md).

## Turning the build step off

```xml
<PropertyGroup>
  <NiteBuildEnabled>false</NiteBuildEnabled>
</PropertyGroup>
```

Useful when a separate CI step runs `nite build`, or for a server-only build of the project. Release builds then publish whatever is in `wwwroot/_nite`, which `dotnet clean` deletes.

## What if the build output is missing?

In production, `MapNiteSpa` and the tag helpers read `wwwroot/_nite/manifest.json`. If it is missing, requests fail with:

```text
wwwroot/_nite/manifest.json was not found. Run `nite build` (publishing does this for you) or run in Development.
```

Usually that means a Debug build was deployed, `NiteBuildEnabled` was false, or the environment is not Development when you expected it to be.


<!-- Source: https://nitefx.dev/docs/guides/observability.html -->

# Telemetry, health checks and Aspire

NiteFx reports what it does as OpenTelemetry traces and metrics and offers a health check, so a slow first page load or a broken `nite.json` shows up in your dashboard instead of in a guess. Under [Aspire](https://aspire.dev), a NiteFx app is an ordinary project resource.

## Traces and metrics

NiteFx uses .NET's own `ActivitySource` and `Meter`, both named `Nite`, so the library takes no OpenTelemetry dependency, and nothing is recorded (or costs anything) until a listener subscribes. Add the names to your OpenTelemetry setup, in the project that uses NiteFx:

```csharp
using Nite.Observability;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;

builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddSource(NiteTelemetry.SourceName));
builder.Services.ConfigureOpenTelemetryMeterProvider(metrics => metrics.AddMeter(NiteTelemetry.MeterName));
```

`ConfigureOpenTelemetry…Provider` adds to whatever `AddOpenTelemetry()` set up elsewhere (such as Aspire's ServiceDefaults), so it works from any project. If you configure OpenTelemetry in one place yourself, `.AddSource(...)` and `.AddMeter(...)` on its builders do the same.

Requests the dev server answers under `/_nite` never reach routing, so NiteFx names their spans after its own routes, as routing does for endpoints: `GET /_nite/src/{**path}`, `GET /_nite/deps/{file}`, `GET /_nite/npm/{**specifier}` and the fixed paths such as `GET /_nite/client.js`. They also get the `http.route` tag.

### Spans

| Span | When | Tags |
|---|---|---|
| `nite.dev.startup` | The dev server starting: package install, initial compiles and pre-bundling in one trace | |
| `nite.dev.compile` | A module compiled for a request; a child of that request's span | `nite.file` |
| `nite.dev.stylesheet` | A stylesheet built for a request | `nite.file` |
| `nite.css.sass`, `nite.css.less`, `nite.css.tailwind`, `nite.css.postcss` | Each stylesheet tool, under the stylesheet it ran for | `nite.file` |
| `nite.dev.hot_update` | A batch of saved files and what the browser was told to do | `nite.files.changed`, `nite.update.kind`, `nite.update.modules` |
| `nite.dev.prebundle` | Pre-bundling dependencies (at startup, or when a new import appears) | `nite.dependencies` |
| `nite.packages.install` | Making `node_modules` match `nite.json` | `nite.packages.count` |
| `nite.packages.resolve` | Resolving versions; only when the lockfile changes | `nite.packages.requested` |
| `nite.packages.materialize` | Extracting packages into `node_modules` | `nite.packages.installed` |
| `nite.tool.download` | Downloading the esbuild or Dart Sass binary, the first time | `nite.package` |
| `nite.build` | A production build | `nite.build.entries` |

Cache hits make no spans, so a warm dev server's request traces stay short. `nite.update.kind` is `update` (Fast Refresh), `css`, `error` (an overlay) or `reload`. A failed span has the error status and an `exception` event, so a Sass syntax error or a package that does not exist is one click away from the request that hit it.

The startup trace waits for the host to start before it begins, because OpenTelemetry subscribes as the host starts. Requests that arrive first wait for startup, as they always have.

### Metrics

| Metric | Unit | Tags |
|---|---|---|
| `nite.dev.compile.duration` | s | `nite.kind` (module, stylesheet) |
| `nite.dev.compiles` | {compile} | `nite.kind`, `nite.cache` (hit, miss) |
| `nite.css.tool.duration` | s | `nite.css.tool` (sass, less, tailwind, postcss) |
| `nite.dev.hot_updates` | {update} | `nite.update.kind` |
| `nite.dev.prebundle.duration` | s | |
| `nite.packages.install.duration` | s | |
| `nite.packages.tarballs` | {tarball} | `nite.cache` (hit, miss) |
| `nite.build.duration` | s | |

## Health check

```csharp
builder.Services.AddHealthChecks().AddNite();
// ...
app.MapHealthChecks("/health");
```

| Where | Status |
|---|---|
| Development | **Degraded** while packages install or dependencies pre-bundle; **Unhealthy** if that failed (often a typo in `nite.json`) or `app.UseNite()` never ran; **Healthy** otherwise, with the number of compiled modules and pre-bundled dependencies |
| Production | **Unhealthy** if `wwwroot/_nite/manifest.json` is missing or unreadable, which usually means the publish did not run `nite build`; **Healthy** otherwise |

It is a readiness check: restarting the app does not fix a broken `nite.json`, so it carries no tags. Pass `tags` to `AddNite` to change that. `MapHealthChecks` answers 200 for Healthy and Degraded and 503 for Unhealthy, unless you set `ResultStatusCodes`.

## Aspire

A NiteFx app needs nothing special to run under Aspire: NiteFx is middleware in your ASP.NET Core project, so `AddProject` runs the dev server along with your API. [`samples/Nite.Aspire`](https://github.com/nite-net/nite/tree/main/samples/Nite.Aspire) is a complete example: a NiteFx React app that calls a separate API service through service discovery.

```csharp
// AppHost.cs
var builder = DistributedApplication.CreateBuilder(args);

var api = builder.AddProject<Projects.Api>("api");

builder.AddProject<Projects.Web>("web")
    .WithExternalHttpEndpoints()
    .WithHttpHealthCheck("/health")
    .WithReference(api);

builder.Build().Run();
```

Leave ServiceDefaults as the template made it: other services share it, and they do not use NiteFx (the health check needs `AddNite()`). Add NiteFx's part in the web project instead, after `AddServiceDefaults()`:

```csharp
builder.AddServiceDefaults();

builder.Services.AddNite();
builder.Services.ConfigureOpenTelemetryTracerProvider(tracing => tracing.AddSource(NiteTelemetry.SourceName));
builder.Services.ConfigureOpenTelemetryMeterProvider(metrics => metrics.AddMeter(NiteTelemetry.MeterName));
builder.Services.AddHealthChecks().AddNite();

var app = builder.Build();
app.UseNite();
app.MapDefaultEndpoints();   // /health and /alive, from ServiceDefaults
```

The dashboard then shows NiteFx's logs and its startup and compile spans inside your request traces, and the web resource turns unhealthy if the dev server fails to start, with the reason in the health check's description. (`MapHealthChecks` answers 200 for Degraded as well as Healthy, so a dev server that is still starting does not count against the resource.)

What to know:

- **Plain HTTP.** Without a development certificate, run the AppHost's `http` launch profile and add `"ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"` to that profile's environment variables, or the AppHost refuses to start.
- **Hot reload.** Saved TypeScript, JSX and CSS update in the browser as usual: the dev server watches files itself. Aspire runs projects with `dotnet run`, not `dotnet watch`, so C# changes need a restart, and the browser's `nite:server-update` event does not fire.
- **Other services' URLs and other settings in client code.** Pass them through [client config](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server), which the server writes into each page as it serves it: the AppHost sets an environment variable on the web project, and `NiteOptions.ClientConfig` hands it to the browser. (`NITE_PUBLIC_` variables also reach client code, but they are inlined when code is compiled, so a production build keeps whatever was set when `nite build` ran.) Calling the other service through your own app, on the same origin, avoids CORS entirely; the sample does that.
- **Application Insights.** See [Application Insights in the browser](https://nitefx.dev/docs/guides/application-insights.md): the sample sends browser and server telemetry to one resource, as one transaction per click.
- **Deploying.** `aspire deploy` builds container images with `dotnet publish`, which runs `nite build`, which needs the `nite` tool on the machine that builds the image. Install it there (`dotnet tool install --global Nite.Cli`), as in [CI](https://nitefx.dev/docs/guides/deployment.md).


<!-- Source: https://nitefx.dev/docs/guides/application-insights.html -->

# Application Insights in the browser

The Application Insights JavaScript SDK works in a NiteFx app like any other package. NiteFx adds three things: the connection string comes from the running server, so one build serves every environment; the SDK loads as its own chunk, after the page; and the browser's telemetry joins the trace of the request that served the page.

[`samples/Nite.Aspire`](https://github.com/nite-net/nite/tree/main/samples/Nite.Aspire) does everything on this page, for both its services and the browser.

## Install

```bash
nite add @microsoft/applicationinsights-web
```

`@microsoft/applicationinsights-react-js` adds a React context and hooks such as `useTrackEvent`; it works too, but this page uses the core SDK directly, which is all most apps need.

## Hand the browser its connection string

The connection string differs per environment, and Azure (or Aspire) sets it on the server as `APPLICATIONINSIGHTS_CONNECTION_STRING` when the app is deployed, after it was built. Pass it through [client config](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server), which the server writes into each page:

```csharp
builder.Services.AddNite(options => options.ClientConfig = context => new
{
    AppInsights = builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"],
    // The trace of the request serving this page, so the browser can join it.
    TraceId = System.Diagnostics.Activity.Current?.TraceId.ToString(),
});
```

```ts
// Client/nite-env.d.ts
declare module "nite:config" {
  export interface NiteClientConfig {
    appInsights?: string;
    traceId?: string;
  }
  export const config: Readonly<NiteClientConfig>;
  export default config;
}
```

The connection string is not a secret: the browser SDK sends it with every batch anyway. (A `NITE_PUBLIC_` variable would also reach the browser, but it is inlined at build time, so each environment would need its own build.)

## Start the SDK after the page

The SDK is about 200 KB minified (80 KB gzipped), as much as React and ReactDOM together. Import it dynamically: production builds put it in a chunk of its own, loaded after the page has rendered, and an app without a connection string never loads it.

```ts
// Client/telemetry.ts
import { config } from "nite:config";
import type { ApplicationInsights } from "@microsoft/applicationinsights-web";

let insights: ApplicationInsights | undefined;

export async function startTelemetry() {
  if (!config.appInsights) return;
  const { ApplicationInsights } = await import("@microsoft/applicationinsights-web");
  insights = new ApplicationInsights({
    config: { connectionString: config.appInsights, enableAutoRouteTracking: true },
  });
  insights.loadAppInsights();
  if (config.traceId) {
    insights.context.telemetryTrace.traceID = config.traceId;   // join the page request's trace
  }
  insights.trackPageView();
}

export function trackEvent(name: string, properties?: Record<string, unknown>) {
  insights?.trackEvent({ name }, properties);
}
```

```tsx
// Client/main.tsx, after createRoot(...).render(...)
void startTelemetry();
```

`enableAutoRouteTracking` records a page view for each client-side route change. To leave development out entirely, guard the call with `if (import.meta.env.PROD)`: the condition is false in development, so the SDK is never imported there.

## One transaction, from page load to the API

With the server sending its own telemetry to the same resource (in an Aspire app, uncomment `UseAzureMonitor()` in ServiceDefaults; elsewhere add the `Azure.Monitor.OpenTelemetry.AspNetCore` package and call `builder.Services.AddOpenTelemetry().UseAzureMonitor()`), these share one operation id:

1. the server request that rendered the page (its trace id went to the browser through client config);
2. the browser's page view, its performance timings and custom events;
3. the browser's `fetch` to your API: the SDK adds a W3C `traceparent` header to same-origin requests;
4. the server request handling that call, and everything it calls in turn, other services included.

So Application Insights' transaction view shows a click from the browser down through every service. Calls to another origin get the header only with `enableCorsCorrelation: true`, and that origin must allow the `traceparent` and `Request-Id` headers in CORS. Calling other services through your own app, on the same origin, avoids both.

## Source maps

Production builds write source maps next to the bundles (`wwwroot/_nite/*.js.map`), and the bundles point at them, so browser developer tools and Application Insights' "unminify" can show original TypeScript and line numbers. To un-minify call stacks in the portal, upload the maps to the storage container linked to your Application Insights resource as part of your release.

## In development

NiteFx's own [telemetry](https://nitefx.dev/docs/guides/observability.md) also reaches Application Insights while you develop, if a connection string is set: dev server startup, compiles and `/_nite` requests. That is useful when debugging NiteFx itself and noise otherwise; set the connection string only in deployed environments (the Aspire sample only adds it when one is configured), or use the Aspire dashboard locally.


<!-- Source: https://nitefx.dev/docs/reference/cli.html -->

# Command-line interface

The `nite` tool creates projects, manages packages, builds for production and runs the dev loop. Run `nite --help`, or `nite  --help`, for the same information in your terminal.

| Command | Aliases | Summary |
|---|---|---|
| [`nite init`](https://nitefx.dev/docs/reference/cli.md#nite-init) | | Create a project, or import an existing one |
| [`nite install`](https://nitefx.dev/docs/reference/cli.md#nite-install) | `add`, `i` | Install packages, or add new ones |
| [`nite remove`](https://nitefx.dev/docs/reference/cli.md#nite-remove) | `rm`, `delete`, `uninstall` | Remove packages |
| [`nite list`](https://nitefx.dev/docs/reference/cli.md#nite-list) | `ls` | Show installed packages |
| [`nite update`](https://nitefx.dev/docs/reference/cli.md#nite-update) | `up` | Check for and apply package updates |
| [`nite build`](https://nitefx.dev/docs/reference/cli.md#nite-build) | | Production build into `wwwroot/_nite` |
| [`nite watch`](https://nitefx.dev/docs/reference/cli.md#nite-watch) | | `dotnet watch` with NiteFx handling the browser |
| [`nite config`](https://nitefx.dev/docs/reference/cli.md#nite-config) | | Show or change settings |
| [`nite cache`](https://nitefx.dev/docs/reference/cli.md#nite-cache) | | Manage the download cache |
| [`nite version`](https://nitefx.dev/docs/reference/cli.md#nite-version) | `--version` | Show versions |
| [`nite update-self`](https://nitefx.dev/docs/reference/cli.md#nite-update-self) | | Update the tool |

## Common options

Commands that work on a project (`install`, `remove`, `list`, `update`, `build`, `watch`) take:

| Option | Meaning |
|---|---|
| `-C`, `--dir <DIRECTORY>` | The project folder (the one with `nite.json`). Defaults to the current folder. |
| `--verbose` | Show debug output. |

Exit codes: `0` on success, `1` on an error, `130` when interrupted with Ctrl+C.

---

## nite init

Create a project, then install its packages.

```text
nite init [DIRECTORY] [OPTIONS]
```

`DIRECTORY` defaults to the current folder. It must be empty (files such as `.git` and `README.md` are fine) unless you pass `--force`, and must not already contain a project file.

| Option | Meaning |
|---|---|
| `-t`, `--template <TEMPLATE>` | `spa` (a React app with an API) or `islands` (Razor Pages with React islands). Defaults to the `init.template` setting, which defaults to `spa`. |
| `-n`, `--name <NAME>` | Project name. Defaults to the folder name. |
| `--from <PATH>` | Import an existing npm, Yarn, pnpm or Bun project (Vite or Create React App). The source is not changed. See [Importing](https://nitefx.dev/docs/guides/importing.md). |
| `--dry-run` | With `--from`: show what would be imported and write nothing. |
| `--force` | Create the project in a folder that already has files. Existing files are never overwritten. |
| `--no-install` | Skip installing packages. |
| `--nite-source <PATH>` | Reference a NiteFx source checkout instead of the `Nite` NuGet package. |
| `--verbose` | Show debug output. |

```bash
nite init                              # SPA in the current folder
nite init my-app                       # SPA in ./my-app
nite init my-site --template islands   # Razor Pages with islands
nite init my-app --from ../vite-app --dry-run
```

## nite install

Install the packages in `nite.json`, or add new ones. Aliases: `nite add`, `nite i`.

```text
nite install [PACKAGES] [OPTIONS]
```

| Argument / option | Meaning |
|---|---|
| `PACKAGES` | Packages to add: `react`, `react@^19`, `@types/react@latest`. Omit to install everything in `nite.json`. |
| `-D`, `--dev` | Add to `devDependencies`. |
| `-E`, `--exact` | Save the exact version instead of a `^` range. |

A bare name or a dist-tag is saved as `^<version>` (or the exact version with `-E`); a range is saved as written. Comments and formatting in `nite.json` are kept.

```bash
nite install
nite add react-router zod
nite add -D @types/node typescript
nite add -E lodash-es@4.17.21
```

## nite remove

Remove packages from `nite.json` and `node_modules`. Aliases: `nite rm`, `nite delete`, `nite uninstall`.

```text
nite remove <PACKAGES> [OPTIONS]
```

```bash
nite rm react-router
```

## nite list

Show installed packages: each direct dependency's range and installed version. Alias: `nite ls`.

```text
nite list [OPTIONS]
```

| Option | Meaning |
|---|---|
| `-a`, `--all` | Include transitive dependencies, with the package they are nested under when not hoisted. |

## nite update

Show current, wanted and latest versions, then update. Alias: `nite up`.

```text
nite update [PACKAGES] [OPTIONS]
```

| Argument / option | Meaning |
|---|---|
| `PACKAGES` | Only these packages. Omit to update everything. |
| `-c`, `--check` | Only report what is outdated; change nothing. |
| `-L`, `--latest` | Move ranges in `nite.json` to the latest versions, across major versions too. |

*Wanted* is the newest version the current range allows; *latest* is the registry's `latest` tag. Without `--latest`, ranges stay as they are and the lockfile moves to the wanted versions.

```bash
nite update --check
nite update
nite update react react-dom --latest
```

## nite build

The production build: installs packages, then builds every entry into `wwwroot/_nite` and prints a table of the outputs and their sizes. `dotnet publish -c Release` runs it for you.

```text
nite build [OPTIONS]
```

See [Production builds and deployment](https://nitefx.dev/docs/guides/deployment.md).

## nite watch

Run `dotnet watch` with NiteFx handling the browser.

```text
nite watch [OPTIONS] [-- DOTNET_WATCH_ARGUMENTS]
```

| Option | Meaning |
|---|---|
| `--browser-refresh` | Keep `dotnet watch`'s own browser refresh, which reloads the page after every C# change. Useful for Razor Pages and MVC; off by default so single-page apps keep their state. |
| `--no-auto-restart` | Let `dotnet watch` ask (or wait for Ctrl+R) when an edit needs a restart, instead of restarting the app automatically. |

Everything after `--` goes to `dotnet watch`. The variables `nite watch` sets, and why, are on [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md#variables-nite-watch-sets).

```bash
nite watch
nite watch --browser-refresh
nite watch -- --launch-profile https
```

## nite config

Show or change settings. Credentials are never stored here; they stay in `.npmrc`. See [Settings and directories](https://nitefx.dev/docs/reference/settings.md).

| Command | Meaning |
|---|---|
| `nite config list` (`ls`) | Effective settings for the current folder. `--show-origin` shows where each value comes from; `-C <dir>` includes another project's `nite.json` and `.npmrc`. |
| `nite config get <KEY>` | Print one setting. |
| `nite config set <KEY> <VALUE>` | Set a value in the user config. |
| `nite config unset <KEY>` (`delete`) | Remove a value from the user config. |
| `nite config path` | Print the user config file's path. |

Keys: `registry`, `@scope:registry` and `init.template`. Registry values must be `http` or `https` URLs; `init.template` must be `spa` or `islands`.

```bash
nite config set @acme:registry https://npm.acme.dev/
nite config set init.template islands
nite config list --show-origin
```

## nite cache

Manage the per-user download cache: package tarballs, registry metadata, and the esbuild and Sass binaries.

| Command | Meaning |
|---|---|
| `nite cache dir` | Print the cache folder. |
| `nite cache clean` (`clear`) | Delete the cache, including folders older NiteFx versions left behind. Everything downloads again on next use. |
| `nite cache verify` | Re-check cached tarballs against their integrity hashes and remove corrupt ones. |

## nite version

Print the nite version, with the esbuild version it drives and the .NET runtime.

```text
$ nite version
nite 0.7.0 (1696a82fcaf5)
esbuild 0.28.2, .NET 10.0.13
```

## nite update-self

Update the `nite` tool with `dotnet tool update`, wherever it is installed: a local tool manifest (when one in the current folder or above lists `Nite.Cli`), the global tools folder, or a custom `--tool-path`.

| Option | Meaning |
|---|---|
| `--version <VERSION>` | Install a specific version. |
| `--prerelease` | Allow prerelease versions. |


<!-- Source: https://nitefx.dev/docs/reference/nite-json.html -->

# nite.json

`nite.json` sits next to the project file and describes the client: where it lives, its packages, and how it is compiled. The dev server, the CLI and production builds all read it, so they always agree.

```jsonc
{
  "clientRoot": "Client",
  "islands": "islands",
  "entries": [],
  "renderer": "react",
  "jsxImportSource": "react",
  "fastRefresh": true,
  "envPrefix": ["NITE_PUBLIC_"],
  "jsxInJs": false,
  "target": "es2022",
  "registry": null,
  "css": {
    "postCss": true,
    "preprocessorOptions": {
      "scss": { "additionalData": null, "loadPaths": [], "silenceDeprecations": [] },
      "less": { "additionalData": null, "paths": [], "javascriptEnabled": false, "globalVars": {}, "modifyVars": {} }
    }
  },
  "dependencies": {},
  "devDependencies": {}
}
```

Every setting is optional; the values above are the defaults. The file may contain `//` and `/* */` comments and trailing commas, and property names are case-insensitive. `nite add` and `nite rm` edit it in place and keep your comments.

While the app runs in development, saving `nite.json` installs packages, re-bundles dependencies and reloads the page. A changed `clientRoot` needs a restart.

## Project structure

### clientRoot

`string`, default `"Client"`

The folder, relative to the project, that holds client source. Everything NiteFx compiles lives under it, and in development its files are served under `/_nite/src/`.

### islands

`string`, default `"islands"`

The folder, relative to `clientRoot`, whose modules can be used as `<island name="...">`. Subfolders become part of the name: `islands/admin/UserTable.tsx` is `admin/UserTable`. See [Islands](https://nitefx.dev/docs/guides/islands.md).

### entries

`string[]`, default `[]`

Extra entry points, relative to `clientRoot`, for the production build:

- HTML pages other than `index.html` (which is an entry automatically when it exists), for example `"admin.html"`;
- modules loaded with `<nite-module src="...">`, for example `"pages/checkout.ts"`.

Islands are entries automatically. In development nothing needs to be listed, but NiteFx warns when a `<nite-module>` points at a module that is missing here, since the production build would not include it.

## Compilation

### jsxImportSource

`string`, default `"react"`

The package that provides the automatic JSX runtime (`<source>/jsx-runtime`, and `<source>/jsx-dev-runtime` in development). Use `"preact"` for Preact, or any library that ships those modules.

### fastRefresh

`boolean`, default `true`

React Fast Refresh in development. It applies when `jsxImportSource` is `"react"` and `react` is in `dependencies`; NiteFx then installs `react-refresh` as an implicit dev dependency. Set to `false` to reload the page on component edits instead.

### jsxInJs

`boolean`, default `false`

Allow JSX in `.js` files, as Create React App does. Off by default, as in Vite. Imported Create React App projects get `true`.

### target

`string`, default `"es2022"`

The esbuild target for production output, a comma-separated list of language versions and browsers (`"es2020"`, `"es2022,safari15"`, `"chrome110,firefox110,safari16"`). When it names only language versions, NiteFx adds Vite's default browser list (`chrome107, edge107, firefox104, safari16`), so CSS gets lowered for those browsers too. Development always compiles for modern browsers.

### renderer

`string`, default `"react"`

The island renderer: `"react"`, or the path (relative to `clientRoot`) of a module that exports `mount(element, component, props)`. See [Custom renderers](https://nitefx.dev/docs/guides/renderers.md).

## Environment

### envPrefix

`string[]`, default `["NITE_PUBLIC_"]`

Environment variables whose names start with one of these prefixes are exposed to client code as `import.meta.env.NAME` and `process.env.NAME`. Others never reach the browser. See [Environment variables](https://nitefx.dev/docs/guides/environment.md).

## Stylesheets

### css.postCss

`boolean`, default `true`

Run the project's PostCSS config (when one exists) on stylesheets. Package stylesheets in `node_modules` are never run through it.

### css.preprocessorOptions.scss

Options for Sass (`.scss` and `.sass`), named as in Vite.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `additionalData` | `string` | none | Prepended to every Sass file, typically `@use` rules for shared variables and mixins. The client root is a load path, so files there can be used by name. |
| `loadPaths` | `string[]` | `[]` | Extra folders (relative to the project) to resolve `@use` and `@import` from. The client root and `node_modules` are always load paths. |
| `silenceDeprecations` | `string[]` | `[]` | Sass deprecation IDs to keep quiet, such as `"import"` or `"global-builtin"`. |

### css.preprocessorOptions.less

Options for Less.

| Key | Type | Default | Meaning |
|---|---|---|---|
| `additionalData` | `string` | none | Prepended to every Less file. |
| `paths` | `string[]` | `[]` | Extra folders (relative to the project) for `@import`. The importing file's folder, the client root and `node_modules` are always searched. |
| `javascriptEnabled` | `boolean` | `false` | Allow inline JavaScript in Less files. |
| `globalVars` | `object` | `{}` | Variables defined before every file, overridable by it. |
| `modifyVars` | `object` | `{}` | Variables defined after every file, overriding it. |

See [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md).

## Packages

### dependencies

`object` of package name → version range, default `{}`

Packages your client code imports. Manage with `nite add` and `nite rm`. See [Packages](https://nitefx.dev/docs/guides/packages.md).

### devDependencies

`object` of package name → version range, default `{}`

Packages installed but never bundled: type packages (`@types/react`), `typescript`, and stylesheet tools (`sass-embedded`, `less`, `tailwindcss`, PostCSS and its plugins).

### registry

`string`, default none

The registry for this project's unscoped packages, for everyone who builds it. It overrides `.npmrc` and the user config; `NITE_REGISTRY` overrides it. Usually `.npmrc` is the better place. See [Private registries](https://nitefx.dev/docs/guides/private-registries.md).

## Examples

A single-page app with React Router and Tailwind:

```json
{
  "clientRoot": "Client",
  "dependencies": {
    "react": "^19.3.1",
    "react-dom": "^19.3.1",
    "react-router": "^8.5.0"
  },
  "devDependencies": {
    "@types/react": "^19.2.0",
    "@types/react-dom": "^19.2.0",
    "tailwindcss": "^4.3.3"
  }
}
```

A Razor site with islands, a page module, and an imported Vite project's environment prefix:

```jsonc
{
  "clientRoot": "Client",
  "islands": "islands",
  "entries": ["site.ts"],              // <nite-module src="site.ts" /> in _Layout.cshtml
  "envPrefix": ["VITE_"],
  "dependencies": { "react": "^19.3.1", "react-dom": "^19.3.1" }
}
```


<!-- Source: https://nitefx.dev/docs/reference/aspnet.html -->

# ASP.NET Core integration

Three extension methods connect NiteFx to an app: `AddNite` registers services, `UseNite` mounts the dev server, and `MapNiteSpa` serves an HTML entry. All are in the `Nite` namespace.

```csharp
using Nite;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddNite();

var app = builder.Build();
app.UseNite();
// ... endpoints, Razor Pages ...
app.MapStaticAssets();
app.MapNiteSpa();
app.Run();
```

## AddNite

```csharp
IServiceCollection AddNite(this IServiceCollection services, Action<NiteOptions>? configure = null)
```

Registers the dev server, the production asset reader and [Nite.Assets.INiteAssets](https://nitefx.dev/api/Nite.Assets.INiteAssets.html), which resolves to whichever applies in the current mode. Required by `UseNite`, `MapNiteSpa` and the tag helpers. Calling it more than once is harmless.

### NiteOptions

| Property | Type | Default | Meaning |
|---|---|---|---|
| `Mode` | [Nite.NiteMode](https://nitefx.dev/api/Nite.NiteMode.html) | `Auto` | `Auto`: the dev server in the Development environment, the build output everywhere else. `Development` or `Production` force one. |
| `ProjectDirectory` | `string?` | the content root | The folder holding `nite.json`, when it is not the content root. |
| `ClientConfig` | `Func<HttpContext, object?>?` | none | Values for client code, worked out per request and read with `import { config } from "nite:config"`. See [Values from the running server](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server). |
| `ClientConfigAsync` | `Func<HttpContext, Task<object?>>?` | none | The same, for an async callback. Set one or the other. |
| `CspNonce` | `Func<HttpContext, string?>?` | none | The request's Content Security Policy nonce, which NiteFx puts on every script and style it writes into a page. See [Content Security Policy](https://nitefx.dev/docs/reference/aspnet.md#content-security-policy). |

```csharp
builder.Services.AddNite(options =>
{
    options.Mode = NiteMode.Production;              // serve the build output while developing
    options.ProjectDirectory = Path.Combine(builder.Environment.ContentRootPath, "frontend");
});
```

## UseNite

```csharp
IApplicationBuilder UseNite(this IApplicationBuilder app)
```

In development, starts the dev server (package install, pre-bundling, file watching) in the background and mounts it at `/_nite`: compiled modules, dependencies, the browser runtime and the hot-update WebSocket. In production it does nothing, because the build output is ordinary static files.

Call it early: before `UseRouting`, `MapStaticAssets` and anything else that could answer `/_nite/...`. It enables WebSockets for its own branch only. The URLs it serves are listed in [Dev server URLs](https://nitefx.dev/docs/reference/dev-server-urls.md).

## MapNiteSpa

```csharp
IEndpointConventionBuilder MapNiteSpa(this IEndpointRouteBuilder endpoints, string page = "index.html", string? apiPrefix = "/api", string? path = null)
```

Serves an HTML entry from the client root for `/` and, as a fallback, for any other `GET` or `HEAD` request to a path without a file extension that no other endpoint handled. Client-side routes survive a refresh, and real endpoints always win.

| Parameter | Meaning |
|---|---|
| `page` | The HTML entry, relative to the client root. |
| `apiPrefix` | Requests under this path never fall back: a mistyped API call gets a 404 instead of a page of HTML. `null` disables the check. |
| `path` | Serve the page only under this path: `"/login"` answers `/login` and `/login/…`. Map several apps this way, plus one without a path for everything else; the more specific path wins. See [More than one page](https://nitefx.dev/docs/guides/single-page-apps.md#more-than-one-page). |

In development the page is read from source on every request, with NiteFx's head (import map, dev client, Fast Refresh runtime) injected. In production it is the built copy from `wwwroot/_nite`, with the request's path base added to its URLs. When `NiteOptions.ClientConfig` is set, its values are added at the top of `<head>`. Pages are sent with `Cache-Control: no-cache`, or `private, no-store` when they carry client config, which may differ per user and should not outlive the visit in the browser's cache either.

It returns the fallback endpoint's convention builder, so endpoint conventions apply:

```csharp
app.MapNiteSpa().RequireAuthorization();       // the whole SPA behind login
```

## INiteAssets

[Nite.Assets.INiteAssets](https://nitefx.dev/api/Nite.Assets.INiteAssets.html) answers "what does this page need?" in the current mode. The tag helpers and `MapNiteSpa` are built on it; use it directly for custom endpoints or layouts.

| Member | Returns |
|---|---|
| `IsDevelopment` | Whether the dev server is active. |
| `GetHeadAsync(context)` | A [Nite.Assets.NiteHead](https://nitefx.dev/api/Nite.Assets.NiteHead.html): the import map, preloads and scripts for `<head>`. `ToHtml()` renders it. |
| `GetIslandAsync(name, context)` | A [Nite.Assets.NiteAsset](https://nitefx.dev/api/Nite.Assets.NiteAsset.html) for an island: its module URL, stylesheets and preloads. |
| `GetModuleAsync(source, context)` | The same for a module in the client root. |
| `GetHtmlAsync(page, context)` | An HTML entry as it should be served. |

Serve a second single-page app at its own path:

```csharp
app.MapGet("/admin/{**path}", async (HttpContext context, INiteAssets assets) =>
    Results.Content(await assets.GetHtmlAsync("admin.html", context), "text/html"));
```

Render NiteFx's head in a layout that is not a Razor view:

```csharp
var head = await assets.GetHeadAsync(context);
html.Append(head.ToHtml());
```

`ToHtml(nonce)` adds a Content Security Policy nonce to each script it writes; `<nite-head />` passes `NiteOptions.CspNonce` itself.

## Content Security Policy

A strict policy allows only scripts that carry a nonce, a random value that changes on every request, so a script injected into the page does not run. NiteFx writes inline scripts and styles of its own (the import map, client config, and in development the dev client, CSS imported from modules and the error overlay), so tell it the request's nonce:

```csharp
builder.Services.AddNite(options => options.CspNonce = context => context.Items["csp-nonce"] as string);
// ...
app.Use(async (context, next) =>
{
    var nonce = Convert.ToBase64String(RandomNumberGenerator.GetBytes(18));
    context.Items["csp-nonce"] = nonce;
    context.Response.Headers.ContentSecurityPolicy =
        $"default-src 'self'; script-src 'self' 'nonce-{nonce}'; style-src 'self' 'nonce-{nonce}'; " +
        "object-src 'none'; base-uri 'none'; frame-ancestors 'none'";
    await next();
});
app.UseNite();
```

Pages from `MapNiteSpa` and `<nite-head />` then get the nonce on every `<script>`, and the styles the dev server injects copy it from the page, so the same policy works in development and production with no `'unsafe-inline'`. Register the middleware before `UseNite()` and your endpoints, so the nonce exists when NiteFx writes a page. [`samples/Nite.Identity`](https://github.com/nite-net/nite/tree/main/samples/Nite.Identity) does this along with the other usual security headers.

## The C# hot reload event

NiteFx registers a `MetadataUpdateHandler` in its assembly. When `dotnet watch` (or an IDE) applies a hot reload to the running app in development, connected pages receive a `nite:server-update` event. There is nothing to configure. See [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md#c-changes).

## Middleware order

A typical full pipeline:

```csharp
var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseNite();                 // before routing and static assets
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

app.MapStaticAssets();
app.MapRazorPages().WithStaticAssets();
app.MapControllers();
app.MapNiteSpa();              // last: it is a fallback

app.Run();
```

## API reference

The generated [API reference](https://nitefx.dev/api/index.html) has every type and member.


<!-- Source: https://nitefx.dev/docs/reference/tag-helpers.html -->

# Tag helpers

Three tag helpers put NiteFx into Razor views. Import them once in `_ViewImports.cshtml`:

```cshtml
@addTagHelper *, Nite
```

## &lt;nite-head&gt;

Writes what a page needs in `<head>` for islands and modules. Put it in your layout, inside `<head>`, before any `<island>` or `<nite-module>`:

```cshtml
<head>
    <meta charset="utf-8" />
    <nite-head />
</head>
```

| Mode | Output |
|---|---|
| Development | The import map for dependencies, the Fast Refresh runtime (when enabled), the dev client and the island loader |
| Production | The island loader with `modulepreload` hints for its chunks (only if the project has islands) |
| Both | The values of `NiteOptions.ClientConfig`, when it is set, for `nite:config` ([details](https://nitefx.dev/docs/guides/environment.md#values-from-the-running-server)) |

It takes no attributes. Without it, islands do not mount.

## &lt;island&gt;

Renders a component from the islands folder.

```cshtml
<island name="TodoList"
        props='new { title = "Today", items = Model.Todos }'
        client="visible">
    <p>Loading…</p>
</island>
```

| Attribute | Type | Default | Meaning |
|---|---|---|---|
| `name` | `string` | (required) | The island's path under the islands folder, without extension: `Counter`, `admin/UserTable`. |
| `props` | `object` | none | Props for the component, serialized as camelCase JSON. |
| `client` | `string` | `load` | When to load: `load`, `idle`, `visible` or `media`. |
| `media` | `string` | `all` | The media query for `client="media"`. |
| `export` | `string` | `default` | The export to render, when it is not the default export. |
| `tag` | `string` | `div` | The wrapper element's tag name. |

The content between the tags is rendered on the server and shown until the island mounts.

**Output**, for `<island name="Counter" props="new { start = 5 }" client="idle" />` in development:

```html
<div data-island="/_nite/src/islands/Counter.tsx" data-name="Counter"
     data-props="{&quot;start&quot;:5}" data-client="idle"></div>
```

In production, `data-island` points at the hashed bundle, and a `<link rel="stylesheet">` for the island's CSS is written right before the element (once per page, however many islands share it).

**Errors.** An unknown `name` throws when the view renders, listing the islands that exist (development) or saying the island is not in the build (production).

## &lt;nite-module&gt;

Loads a module that is not an island, such as page-specific behavior or a stylesheet entry.

```cshtml
<nite-module src="pages/checkout.ts" />
```

| Attribute | Type | Meaning |
|---|---|---|
| `src` | `string` | The module's path relative to the client root. The extension may be left off. |

Writes a `<script type="module">`, plus in production `<link rel="stylesheet">` for its CSS and `modulepreload` hints for its chunks. List the module in [`entries`](https://nitefx.dev/docs/reference/nite-json.md#entries) so production builds include it; development logs a warning when you forget.

## Data attributes

The island loader reads these from any element, so you can also write islands by hand (from a JavaScript template, say):

| Attribute | Meaning |
|---|---|
| `data-island` | The module URL to import. |
| `data-name` | A name for error messages. |
| `data-props` | Props as JSON. |
| `data-client` | `load`, `idle`, `visible` or `media`. |
| `data-media` | The media query for `media`. |
| `data-export` | The export to render. |

See [Browser runtime](https://nitefx.dev/docs/reference/browser-runtime.md#the-island-loader).


<!-- Source: https://nitefx.dev/docs/reference/browser-runtime.html -->

# Browser runtime

NiteFx adds a little JavaScript to your pages: the island loader in development and production, and the dev client and Fast Refresh runtime in development only.

## Events

### nite:server-update

Dispatched on `window` in development when C# hot reload changes the running server.

```ts
addEventListener("nite:server-update", (event) => {
  const { types } = (event as CustomEvent<{ types: string[] }>).detail;
  console.log("server changed:", types);   // ["MyApp.TodoStore", ...]
  reload();
});
```

| `detail` property | Type | Meaning |
|---|---|---|
| `types` | `string[]` | Full names of the .NET types the update changed (may be empty). |

It never fires in production. A small helper that fits `useEffect`:

```ts
export function onServerUpdate(callback: () => void) {
  addEventListener("nite:server-update", callback);
  return () => removeEventListener("nite:server-update", callback);
}
```

## The dev client

`/_nite/client.js`, injected in development. It:

- connects to the dev server's WebSocket (`/_nite/ws`) and applies messages: hot updates, stylesheet swaps, reloads and errors;
- shows the error overlay (a `<nite-error-overlay>` element with its own shadow DOM) and clears it when the failing file is fixed;
- reconnects when the connection drops, and if the server restarted, reloads the page once the server answers again;
- dispatches `nite:server-update`.

Updates are logged to the console at the `debug` level (`[nite] hot updated src/App.tsx`).

## The Fast Refresh runtime

`/_nite/refresh.js`, injected before any React code runs when Fast Refresh is enabled. It sets up `react-refresh`'s runtime, which modules compiled by the dev server register their components with. Nothing in your code calls it.

## The island loader

Loaded by `<nite-head>` on pages with islands. It finds elements with a `data-island` attribute, loads each one's module when its strategy says so, and mounts the component through the renderer.

| `data-client` | Loads |
|---|---|
| `load` (or none) | Immediately |
| `idle` | On `requestIdleCallback` (2 s timeout), or after 200 ms where unsupported |
| `visible` | When the element is within 200 px of the viewport (`IntersectionObserver`) |
| `media` | When `matchMedia(data-media)` matches, now or later |

A `MutationObserver` on the document mounts islands added later and unmounts islands that are removed, calling the cleanup function the renderer returned. An island that fails to load logs `[nite] island <name> failed:` with the error and does not affect other islands.

## The renderer contract

```ts
export function mount(
  element: HTMLElement,
  component: unknown,
  props: object,
): void | (() => void) | Promise<void | (() => void)>;
```

The default renderer uses React's `createRoot`. See [Custom renderers](https://nitefx.dev/docs/guides/renderers.md).

## Global names

The runtime defines no globals in production. In development, `window.__NITE_REFRESH__` holds the Fast Refresh runtime when it is enabled, and `react-refresh` installs React's DevTools hook (`__REACT_DEVTOOLS_GLOBAL_HOOK__`) if no DevTools extension already has.


<!-- Source: https://nitefx.dev/docs/reference/msbuild.html -->

# MSBuild properties

The `Nite` package brings MSBuild targets (`build/Nite.targets`), imported automatically into any project that references it. They keep client files out of the build, and run `nite build` for Release builds.

## What the targets do

| When | What |
|---|---|
| Always | Add `node_modules/**` and `.nite/**` to `DefaultItemExcludes`, so MSBuild never walks them. |
| Always | Mark the client root, `nite.json` and `nite.lock.json` as never copied to the build or publish output. |
| Always | Remove `wwwroot/_nite/**` from content, so a Debug build never serves a stale production build. |
| `NiteBuildEnabled` is `true` (Release by default) | Run `$(NiteCommand) build --dir "$(MSBuildProjectDirectory)"` after project references resolve and before static web assets are collected, then add `wwwroot/_nite/**` as content so it publishes. |
| `dotnet clean` | Delete `wwwroot/_nite`. |

## Properties

| Property | Default | Meaning |
|---|---|---|
| `NiteBuildEnabled` | `true` when `Configuration` is `Release`, otherwise empty | Whether builds run `nite build`. Set `false` to skip it (a separate CI step builds the client, say), or `true` to build the client in Debug too. |
| `NiteCommand` | `nite`, or `"dotnet" "$(NiteCliPath)"` when `NiteCliPath` is set | The command that runs the CLI. Use `dotnet tool run nite` for a [local tool](https://learn.microsoft.com/dotnet/core/tools/local-tools-how-to-use). |
| `NiteCliPath` | empty | Path to `Nite.Cli.dll`, for projects that build against a NiteFx source checkout (`nite init --nite-source` sets it). |
| `NiteClientRoot` | `Client` | The client folder kept out of the build output. Set it when `clientRoot` in `nite.json` is something else. |
| `NiteDotnet` | `$(DOTNET_HOST_PATH)`, or `dotnet` | The `dotnet` executable used with `NiteCliPath`. |

Set them in the project file:

```xml
<PropertyGroup>
  <!-- nite is a local tool in this repository (.config/dotnet-tools.json). -->
  <NiteCommand>dotnet tool run nite</NiteCommand>

  <!-- The client lives in "frontend" (and nite.json says so). -->
  <NiteClientRoot>frontend</NiteClientRoot>
</PropertyGroup>
```

Or on the command line:

```bash
dotnet publish -c Release -p:NiteBuildEnabled=false
```

## Building against a source checkout

Projects created with `nite init --nite-source <path>` reference the library and the CLI project directly and import the targets from the checkout:

```xml
<ItemGroup>
  <ProjectReference Include="..\nite\src\Nite\Nite.csproj" />
  <!-- Built first so Release builds can run `nite build`; not referenced as an assembly. -->
  <ProjectReference Include="..\nite\src\Nite.Cli\Nite.Cli.csproj" ReferenceOutputAssembly="false" Private="false" />
</ItemGroup>

<PropertyGroup>
  <NiteCliPath>$(MSBuildThisFileDirectory)..\nite\src\Nite.Cli\bin\$(Configuration)\net10.0\Nite.Cli.dll</NiteCliPath>
</PropertyGroup>

<Import Project="..\nite\build\Nite.targets" />
```

If `NiteCliPath` points at a file that does not exist, the build fails with a message saying so.


<!-- Source: https://nitefx.dev/docs/reference/settings.html -->

# Settings and directories

Per-project settings live in `nite.json`. Per-user settings and downloads live where the XDG Base Directory spec says they go, and npm's `.npmrc` files are honored as they are.

## Directories

| | Linux and macOS | Windows | Override |
|---|---|---|---|
| Config (`config.json`) | `~/.config/nite` | `%APPDATA%\nite` | `NITE_CONFIG_DIR`, then `XDG_CONFIG_HOME` |
| Cache | `~/.cache/nite` | `%LOCALAPPDATA%\nite\cache` | `NITE_CACHE_DIR`, then `XDG_CACHE_HOME` |
| Data | `~/.local/share/nite` | `%LOCALAPPDATA%\nite\data` | `NITE_DATA_DIR`, then `XDG_DATA_HOME` |
| State | `~/.local/state/nite` | `%LOCALAPPDATA%\nite\state` | `NITE_STATE_DIR`, then `XDG_STATE_HOME` |

`XDG_*` variables apply on every OS when set to an absolute path; `nite` is appended to them. `NITE_*_DIR` variables name the folder itself.

The cache holds:

| Folder | Contents |
|---|---|
| `tarballs/` | Package tarballs, by integrity hash |
| `metadata/` | Registry metadata, with ETags for revalidation |
| `esbuild/` | The esbuild binary, per version and platform |
| `sass/` | The Dart Sass binary, per version and platform |

Everything in it can be deleted at any time (`nite cache clean`); it is downloaded again on demand. `nite cache clean` also removes the download folders earlier NiteFx builds used (`~/.local/share/nite/tarballs` and `esbuild` on Linux and macOS, the same under `%LOCALAPPDATA%\nite` on Windows).

## The user config

`config.json` in the config folder, edited with `nite config`:

```json
{
  "registry": "https://artifacts.acme.dev/api/npm/npm/",
  "@acme:registry": "https://npm.acme.dev/",
  "init.template": "islands"
}
```

| Key | Meaning |
|---|---|
| `registry` | The registry for unscoped packages. |
| `@scope:registry` | The registry for one scope. |
| `init.template` | The template `nite init` uses when `--template` is not given: `spa` or `islands`. |

Credentials are refused here; keep them in `.npmrc`. See [Private registries](https://nitefx.dev/docs/guides/private-registries.md).

## Precedence

Highest first:

1. `NITE_REGISTRY` (for `registry` only)
2. `registry` in the project's `nite.json`
3. The project's `.npmrc` (next to `nite.json`)
4. The user config (`config.json`)
5. The user's `~/.npmrc` (or the file named by `NPM_CONFIG_USERCONFIG`)
6. Defaults: `registry` is `https://registry.npmjs.org/`, `init.template` is `spa`

`nite config list --show-origin` shows the effective value of each setting and where it came from.

## .npmrc support

| Setting | Supported |
|---|---|
| `registry=` | Yes |
| `@scope:registry=` | Yes |
| `//host/path/:_authToken=` | Yes |
| `//host/path/:_auth=` | Yes |
| `//host/path/:username=` and `:_password=` | Yes |
| `${VAR}` expansion in values | Yes |
| `always-auth`, proxies, certificates, `strict-ssl` | No; NiteFx uses the system's proxy and certificate settings through .NET |

## Project-level files

| File | Purpose |
|---|---|
| `nite.json` | Project settings and packages. [Reference](https://nitefx.dev/docs/reference/nite-json.md). |
| `nite.lock.json` | Resolved package versions. |
| `.npmrc` | Registries and credentials for this project. |
| `.env*` | Public environment variables for client code. [Guide](https://nitefx.dev/docs/guides/environment.md). |


<!-- Source: https://nitefx.dev/docs/reference/environment-variables.html -->

# Environment variables

Variables that change how NiteFx behaves. For variables your client code reads (`NITE_PUBLIC_*`), see [Environment variables and path aliases](https://nitefx.dev/docs/guides/environment.md).

## Read by NiteFx

| Variable | Meaning |
|---|---|
| `NITE_REGISTRY` | The registry for unscoped packages, overriding every other setting. |
| `NITE_CONFIG_DIR` | The folder for `config.json`. |
| `NITE_CACHE_DIR` | The download cache folder. |
| `NITE_DATA_DIR`, `NITE_STATE_DIR` | Data and state folders (reserved). |
| `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME` | Base folders, on every OS, when the `NITE_*_DIR` variable is not set. `nite` is appended. |
| `NITE_ESBUILD_PATH` | Use this esbuild binary instead of downloading one. It must be the version NiteFx expects (`nite version` prints it). |
| `NITE_SASS_PATH` | Use this Dart Sass folder (as in Dart Sass's standalone release: `src/dart` and `src/sass.snapshot`) instead of downloading one. |
| `NPM_CONFIG_USERCONFIG` | The user `.npmrc` to read instead of `~/.npmrc`. |
| `COLUMNS` | Terminal width for CLI tables when output is redirected. |
| `ASPNETCORE_ENVIRONMENT` | Through ASP.NET Core: `Development` turns on the dev server (see [Development and production](https://nitefx.dev/docs/concepts/development-and-production.md)). |
| `NITE_PUBLIC_*` (or your `envPrefix`) | Exposed to client code at build time. |

Any variable can also appear in `.npmrc` values as `${NAME}`.

## Set by nite watch

| Variable | Value | Effect |
|---|---|---|
| `DOTNET_WATCH_SUPPRESS_BROWSER_REFRESH` | `1` | `dotnet watch` does not inject its reload script; NiteFx's client handles the browser. Skipped with `--browser-refresh`. |
| `DOTNET_WATCH_RESTART_ON_RUDE_EDIT` | `1` | Edits that need a restart restart the app instead of prompting. Skipped with `--no-auto-restart`. |

A value you set yourself is left alone. See [Hot reload](https://nitefx.dev/docs/guides/hot-reload.md).

## Offline and air-gapped machines

NiteFx downloads three kinds of things: packages, the esbuild binary and (for Sass) the Dart Sass binary. On a machine without registry access:

1. Point `NITE_REGISTRY` (or `.npmrc`) at an internal mirror, which serves all three; or
2. Pre-fill the cache on a connected machine and copy `~/.cache/nite` over; or
3. Provide the binaries with `NITE_ESBUILD_PATH` and `NITE_SASS_PATH`, and commit `nite.lock.json` so installs need only tarballs (from a mirror or the cache).


<!-- Source: https://nitefx.dev/docs/reference/dev-server-urls.html -->

# Dev server URLs

In development, `UseNite()` answers every request under `/_nite`. You rarely need these URLs directly, but they help when reading the network tab.

All URLs are relative to the app's path base.

| URL | Returns |
|---|---|
| `/_nite/src/<path>` | A file from the client root. Modules (`.ts`, `.tsx`, `.jsx`, `.js`, `.mts`, `.mjs`) are compiled to JavaScript; stylesheets are built to CSS; anything else is sent as is. |
| `/_nite/src/<path>?import` | The same file as a JavaScript module: a stylesheet that injects itself (with the class map for CSS modules), JSON as its default export, or an asset's URL. |
| `/_nite/src/<path>?t=<timestamp>` | A module after a hot update; the timestamp makes the browser fetch the new version. |
| `/_nite/deps/<name>.js?v=<hash>` | A pre-bundled dependency (from the import map). Cached by the browser for a year: the hash changes when the dependencies do. |
| `/_nite/deps/chunk-<hash>.js` | Code shared between pre-bundled dependencies. |
| `/_nite/npm/<package>/<file>` | A file from `node_modules`, such as a font a package's CSS references. Package stylesheets (`@mantine/core/styles.css`) are built through the stylesheet pipeline. |
| `/_nite/client.js` | The dev client. |
| `/_nite/refresh.js` | The Fast Refresh runtime. |
| `/_nite/runtime/islands.js` | The island loader. |
| `/_nite/runtime/renderer.js` | The island renderer (React, or yours). |
| `/_nite/ws` | The hot-update WebSocket. |

Source files are served with `Cache-Control: no-cache` and an `ETag`, so a reload revalidates rather than re-downloads.

When compiling fails, a module request returns a small module that shows the error overlay and throws, so the overlay appears even on a fresh page load.

## Messages on the WebSocket

The server sends JSON messages; the dev client handles them.

| `type` | Fields | Client action |
|---|---|---|
| `update` | `updates: [{ path, url, timestamp }]`, `cleared: string[]` | Re-import the modules and run Fast Refresh; hide overlays for the cleared files. |
| `css` | `path`, `url` | Swap the stylesheet in place. |
| `reload` | | Reload the page (once the server answers). |
| `error` | `message`, `file`, `line`, `column`, `lineText` | Show the overlay. |
| `server-update` | `types: string[]` | Dispatch `nite:server-update`. |

These are internal and may change between versions.