# 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.

Every page below is plain Markdown. All of them except the optional ones are also in one file: [llms-full.txt](https://nitefx.dev/llms-full.txt).

## Docs

- [Introduction](https://nitefx.dev/docs/introduction.md): What NiteFx is, the problem it solves, and how it compares to the usual ways of putting a React frontend on ASP.NET Core.
- [Getting started](https://nitefx.dev/docs/getting-started.md): Install the NiteFx CLI, create a React single-page app or a Razor site with islands, and run it with hot reload.
- [Tutorial: a full-stack app](https://nitefx.dev/docs/tutorial.md): Build a small todo app with an ASP.NET Core API and a React frontend, and use every part of NiteFx's dev loop along the way.
- [How NiteFx works](https://nitefx.dev/docs/concepts/architecture.md): The moving parts behind NiteFx, from the esbuild service and the npm client to Fast Refresh, the stylesheet pipeline and the production build.
- [Project layout](https://nitefx.dev/docs/concepts/project-layout.md): The files and folders in a NiteFx project, what each one is for, and which ones belong in source control.
- [Development and production](https://nitefx.dev/docs/concepts/development-and-production.md): How NiteFx behaves in each mode, how it decides which one it is in, and what changes between them.
- [Limits and non-goals](https://nitefx.dev/docs/limits.md): What NiteFx deliberately does not do, and what it does not do yet.
- [Roadmap](https://nitefx.dev/docs/roadmap.md): Where NiteFx is going next, in the order we plan to ship it.
- [Troubleshooting](https://nitefx.dev/docs/troubleshooting.md): Common problems with NiteFx and how to fix them.
- [Changelog](https://nitefx.dev/docs/changelog.md): Notable changes in each version of NiteFx.

## Guides

- [Single-page apps](https://nitefx.dev/docs/guides/single-page-apps.md): Serve a React (or plain TypeScript) single-page app from ASP.NET Core with index.html as the entry, client-side routing and an API on the same origin.
- [Islands in Razor Pages](https://nitefx.dev/docs/guides/islands.md): Put interactive React components into server-rendered Razor Pages and MVC views with the island tag helper, with control over when each one loads.
- [Hot reload and nite watch](https://nitefx.dev/docs/guides/hot-reload.md): How client and server changes reach the browser during development, what keeps state and what reloads, and how nite watch drives dotnet watch.
- [TypeScript and JSX](https://nitefx.dev/docs/guides/typescript.md): How NiteFx compiles TypeScript and JSX, how to set up tsconfig and type declarations, and how to type-check in CI.
- [Environment variables and path aliases](https://nitefx.dev/docs/guides/environment.md): Expose configuration to client code safely with .env files and envPrefix, and use tsconfig path aliases such as @/components.
- [Custom renderers](https://nitefx.dev/docs/guides/renderers.md): Render islands with Preact, Solid, Lit or plain DOM code by replacing NiteFx's React renderer with a module of your own.
- [Packages and the lockfile](https://nitefx.dev/docs/guides/packages.md): Add, remove and update npm packages with the NiteFx CLI, how versions are resolved and locked, and what the installer does and does not do.
- [Private registries](https://nitefx.dev/docs/guides/private-registries.md): Install packages from a private npm registry, a mirror or a per-scope registry, with credentials from .npmrc.
- [Stylesheets](https://nitefx.dev/docs/guides/stylesheets.md): CSS, CSS modules, Sass, Less, Tailwind CSS and PostCSS in NiteFx, how the pipeline runs in development and production, and how hot updates follow your dependencies.
- [Tailwind CSS](https://nitefx.dev/docs/guides/tailwind.md): Use Tailwind CSS 4 in a NiteFx project, with class names found in React components and Razor views alike.
- [Mantine](https://nitefx.dev/docs/guides/mantine.md): Use the Mantine React component library in a NiteFx project, with postcss-preset-mantine, CSS modules and optional Sass, following Mantine's Vite guide.
- [Importing a Vite or CRA project](https://nitefx.dev/docs/guides/importing.md): Bring an existing Vite or Create React App frontend into a NiteFx project, keeping the exact package versions it runs today.
- [Production builds and deployment](https://nitefx.dev/docs/guides/deployment.md): How NiteFx builds the client for production, how dotnet publish includes it, and how to deploy with CI, Docker and a CDN.
- [Telemetry, health checks and Aspire](https://nitefx.dev/docs/guides/observability.md): NiteFx's OpenTelemetry traces and metrics, its health check, and running a NiteFx app under Aspire.
- [Application Insights in the browser](https://nitefx.dev/docs/guides/application-insights.md): Send page views, errors, events and fetch calls from a NiteFx app to Application Insights, configured per environment and correlated with the server.

## Reference

- [Command-line interface](https://nitefx.dev/docs/reference/cli.md): Every NiteFx command, its arguments, options and aliases.
- [nite.json](https://nitefx.dev/docs/reference/nite-json.md): Every setting in nite.json, with its type, default and effect.
- [ASP.NET Core integration](https://nitefx.dev/docs/reference/aspnet.md): AddNite, NiteOptions, UseNite, MapNiteSpa and INiteAssets, the parts of NiteFx your Program.cs uses.
- [Tag helpers](https://nitefx.dev/docs/reference/tag-helpers.md): Reference for the nite-head, island and nite-module tag helpers used in Razor Pages and MVC views.
- [Browser runtime](https://nitefx.dev/docs/reference/browser-runtime.md): The client-side pieces NiteFx adds to pages, the events they raise and the contracts they expect.
- [MSBuild properties](https://nitefx.dev/docs/reference/msbuild.md): The MSBuild targets the Nite package adds to a project, and the properties that control them.
- [Settings and directories](https://nitefx.dev/docs/reference/settings.md): Where NiteFx keeps per-user configuration and cache files, the settings it reads, and the order they apply in.
- [Environment variables](https://nitefx.dev/docs/reference/environment-variables.md): Every environment variable NiteFx reads or sets.
- [Dev server URLs](https://nitefx.dev/docs/reference/dev-server-urls.md): The URLs the development server answers under /_nite, and what each one returns.

## Optional

- [Contributing](https://nitefx.dev/docs/contributing.md): Build NiteFx from source, run its tests, and contribute to NiteFx or to this documentation.
- [Code signing policy](https://nitefx.dev/docs/code-signing.md): How NiteFx's release binaries are signed, who can change the code, and who approves each signing.
- [Privacy policy](https://nitefx.dev/docs/privacy.md): NiteFx collects no personal information and has no telemetry. These are the only network connections it makes, and why.
- [API reference](https://nitefx.dev/api/index.html): every public type and member of the NiteFx library (the `Nite` package), generated from its XML documentation comments