NE.Standard

Getting Started

NE.Standard is a server-driven UI framework: you write a view (a component tree) and a controller (observable state and commands), the framework compiles and renders them, and keeps the rendered page in sync in both directions. This walks through wiring that up, from an empty folder to a first page.

Two projects

An application is a class library, and the web project is its host and nothing else:

App/        a class library — views, controllers, the application's startup with its routes, words and services
App.Web/    an ASP.NET Core project — Program.cs and the web startup, which names the library's startup

The library is written against the platform-independent packages only, so a second platform — a desktop host — is a second small project over the same library, and the library's tests run with no browser and no web server (testing). The framework's own demo is split the same way (examples/DemoApp and examples/DemoApp.Web). Nothing stops a single web project from holding everything, but nothing is gained by it either: the split costs a project reference.

dotnet new classlib -o App
dotnet new web -o App.Web
dotnet add App.Web reference App

Install

The framework's packages are installed at one version, each in the project it belongs to:

Project Packages What they bring
App NE.Standard.UI The engine — the compiler, the runtime, the binding model — the built-in components, and the generators that write a controller's observable members.
NE.Standard.UI.Extensions Optional: the presets, a form or a page's regions in one call (presets).
App.Web NE.Standard.UI.Web The ASP.NET Core host: the shell, the SignalR channel, file transfer, the embedded TypeScript client.
NE.Standard.UI.Web.Renderers The HTML renderers for the built-in components.
dotnet add App package NE.Standard.UI
dotnet add App package NE.Standard.UI.Extensions
dotnet add App.Web package NE.Standard.UI.Web
dotnet add App.Web package NE.Standard.UI.Web.Renderers

An add-on comes in the same two halves: the component in the library, its rendering in the host — NE.Standard.UI.CodeInput in App, NE.Standard.UI.Web.CodeInput in App.Web; the icons' names (NE.Standard.UI.Icons.Material) in App, their glyphs (NE.Standard.UI.Web.Icons.Material) in App.Web. The add-ons page shows each add-on's install and registration, and the packages page lists every half. A library that lists its packages (dotnet list App package --include-transitive) shows no NE.Standard.UI.Web package: if one appears, a web type has crept into the application.

Each package brings the namespaces an application writes against as global usings, so the samples here have no using line for the framework. A project that would rather write its own sets <NEStandardUIImplicitUsings>false</NEStandardUIImplicitUsings>. The namespaces a package author needs — the compiled view, the web render contracts, the renderer foundation — are left out; a package imports those itself.

Two startup classes

Configuration is split in two, one class in each project. The library's startup is the application: its routes, its words, its persistence, and the services its controllers take — a database context factory, an HTTP client, a hosted service that warms a cache. The host's startup adds what only the web needs: the renderers.

// App/AppStartup.cs
using Microsoft.Extensions.DependencyInjection;

public sealed class AppStartup : UIStartupBase
{
    protected override void ConfigureServices(IServiceCollection services)
        => services.AddSingleton(TimeProvider.System);

    protected override void ConfigureApplication(UIApplicationBuilder application)
        => application.Route<CounterView, CounterController>("/");
}
// App.Web/AppWebStartup.cs
internal sealed class AppWebStartup : WebStartupBase<AppStartup>
{
    protected override void ConfigureServices(IServiceCollection services)
        => services.AddStandardRenderers();
}

AddStandardRenderers() registers the renderers for the built-in components — call it once from the host's ConfigureServices. application.Route<TView, TController>(route) registers a page with a controller; application.Route<TView>(route) registers one with no controller, for a page that has nothing to bind.

The application's services belong in AppStartup.ConfigureServices, not in Program.cs: registered there, a desktop host and the library's tests get them too. Program.cs keeps what is the web server's own — its logging, its authentication scheme, a reverse proxy's headers. A library that keeps its startup internal names the host for it in its project file:

<ItemGroup>
  <InternalsVisibleTo Include="App.Web" />
</ItemGroup>

Program.cs

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

WebStartupBuilder.Configure<AppWebStartup, AppStartup>(builder.Services);

WebApplication app = builder.Build();

// The framework maps a catch-all GET route, which matches every path — static files must be served
// (and routing added) before that map, or every static file comes back as a rendered page.
app.UseStaticFiles();
app.UseRouting();

await app.MapStandardUIWebAsync();

await app.RunAsync();

WebStartupBuilder.Configure<TWebStartup, TStartup>(services) runs both startup classes. app.MapStandardUIWebAsync() maps the asset endpoints, the file endpoints, the SignalR hub, and the catch-all page route — in that order, which is why UseStaticFiles/UseRouting must run first and by hand rather than through MapStaticAssets() (its precompressed variants collide with the framework's own response compression).

A first view and controller

Both live in the library. A view declares the component tree; a controller holds the state a component binds to.

internal sealed class CounterView : UIViewBase, IUIViewDefinition
{
    public static string ViewKey => "counter";

    protected override IVisualComponent CreateContent()
        => new ContainerComponent()
            .SetPadding(UIThickness.Uniform(16))
            .AddChild(new TextComponent().BindTitle(nameof(CounterController.Count)))
            .AddChild(new ButtonComponent()
                .OnClick(nameof(CounterController.Increment))
                .SetTitle("Add one")
            );
}
internal sealed partial class CounterController : UIControllerBase
{
    [RecursiveMember]
    public partial int Count { get; set; }

    [UICommand]
    public void Increment() => Count++;
}

BindTitle binds TextComponent.Title to the controller's Count path; OnClick wires the button to the Increment command by name. [RecursiveMember] generates the notifying setter for Count and the path segment a binding resolves against; [UICommand] makes Increment callable from the client. Register the route in AppStartup.ConfigureApplication as shown above.

Running it

dotnet run --project App.Web

Requires the .NET 11 SDK and nothing else: the TypeScript client is built into NE.Standard.UI.Web already, so an application that installs the packages needs no Node.

Icons

Icons are separate packages in the same two halves: Material Symbols' names in the library, its glyphs in the host.

dotnet add App package NE.Standard.UI.Icons.Material
dotnet add App.Web package NE.Standard.UI.Web.Icons.Material

Register the glyphs an application actually uses in the host's ConfigureServices:

protected override void ConfigureServices(IServiceCollection services)
{
    services.AddStandardRenderers();
    services.AddMaterialWebIcons(MaterialIcons.Settings, MaterialIcons.Outlined(MaterialIcons.Save));
}

Only the glyphs named this way get a class — the font carries every glyph either way, so the page's stylesheet stays short, and a misspelt name fails at startup rather than drawing nothing. Pass plain MaterialIcons.* names and MaterialIcons.Outlined(...) values directly, or pass an explicit MaterialIconStyle flags mask (Fill, Outlined) first when every listed name should register both drawings.

An agent's map

Coding agents working in an application's repository can learn the framework from the skills/ne-standard skill shipped in the repository (SKILL.md, components.md, and the task-focused modules under references/), together with the live guides at https://akievansdev.github.io/NE.Standard/. Copy or symlink skills/ne-standard into your workspace's agent skills folder (.agents/skills/ne-standard, .gemini/skills/ne-standard, or .claude/skills/ne-standard).

Where to go next

The counter is the whole model: a view, a controller, a route. A first real screen is three more pages away — a list bound to a collection (Items), a form with validation and a submit (Binding, Validation), and a sign-in page with a route behind it (Security, Signing in); the demo's Screens pages (examples/DemoApp) show each of them.

  • Designing a page — which component for which job, and the choices that keep a page readable on a phone, a tablet and a desktop.
  • Views — the component tree, placement grid, and the fluent authoring style.
  • Presets — the shorter way to write real screens: a page's regions, a form, a row of buttons, a text in a role, each in one call.
  • Controllers — observable state, commands, and the request lifecycle.
  • Binding — paths, scopes, modes, and validation.
  • Interactions and effects — client-side reactions and what a command can return.
  • Routing — registering more than one route, route parameters, and filters.
  • Web hosting — the ASP.NET Core host in depth, and how to extend it.
  • Components — the built-in component catalogue.