RazorDocs Search
Section Start Here
Guide

AppSurface v0.1 package chooser

Start with the package that matches the app you are building, then add optional web modules and support surfaces only when you need them.

Source of truth

View source Edit this page

Last updated

Status

v0.1 chooser

This page is generated from evaluated project metadata plus a curated manifest of what first-time AppSurface adopters should install directly.

Safe To Consume

Scope: Repository-wide. The chooser covers AppSurface's coordinated v0.1 package family, support packages, and proof-host surfaces.

Freshness: Regenerated in CI whenever the package surface or chooser guidance changes on main.

Migration: Read the pre-1.0 upgrade policy

Record

Package READMEs remain the deep reference. This chooser is the public install map for the current repo state.

  • packages/package-index.yml
  • README.md
  • releases/README.md

Generated from packages/package-index.yml and evaluated project metadata. Do not edit this file by hand.

AppSurface v0.1 is a coordinated .NET 10 package family. Start with the package that matches the app you're building, then add optional modules only when your app needs them.

All direct-install packages and tools currently target net10.0. Library package rows use dotnet package add; in .NET 10, dotnet package add and dotnet add package are equivalent. Tool rows use dotnet tool install.

Web app

Install this first for a normal ASP.NET Core app with AppSurface modules when you want the base web startup pipeline before layering on optional UI or docs packages.

Bashdotnet package add ForgeTrust.AppSurface.Web

What you get: Base ASP.NET Core hosting, middleware and endpoint composition, conventional browser error-page hooks, and the core AppSurface web module contract.

Not included: OpenAPI generation, Scalar UI, RazorWire reactive UI, Tailwind build integration, or the RazorDocs host.

Read next: examples/web-app/README.md

Release and readiness:

Also building...

  • Start with ForgeTrust.AppSurface.Console for CLI commands or worker-style processes that should share AppSurface module composition.
  • Add ForgeTrust.AppSurface.Dependency.Autofac when your app already uses Autofac and your modules need Autofac-specific registrations.
  • Start with ForgeTrust.AppSurface.Aspire for distributed app-model projects and service-default composition.
  • Add ForgeTrust.AppSurface.Web.Scalar after ForgeTrust.AppSurface.Web.OpenApi when you want a hosted API reference UI.
  • Add ForgeTrust.RazorWire when you want reactive Razor UI, Turbo-style streams, and server-rendered islands.
  • Add ForgeTrust.AppSurface.Web.Tailwind when you want Tailwind without a separate Node.js asset pipeline.

Package matrix

Swipe to compare package details on narrow screens.

Package Use when Install Includes Does not include Start here Release
ForgeTrust.AppSurface.Core Install this directly only when you are authoring reusable AppSurface modules or host integrations instead of starting from a web, console, or Aspire package. dotnet package add ForgeTrust.AppSurface.Core Core module abstractions, dependency graph orchestration, AppSurfaceStartup, and StartupContext. ASP.NET Core hosting, CliFx command hosting, Aspire app-model helpers, or optional integrations. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Config Add this when your AppSurface modules need strongly typed configuration primitives instead of ad hoc configuration lookups. dotnet package add ForgeTrust.AppSurface.Config AppSurfaceConfigModule, typed config objects, configuration providers, source-aware audit reports, and explicit configuration access patterns. Web hosting, UI docs, caching, or a separate secret-management system. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Caching Add this when your modules need lightweight in-process memoization and cache policy primitives. dotnet package add ForgeTrust.AppSurface.Caching AppSurfaceCachingModule, IMemo or Memo helpers, and cache policy primitives on top of Microsoft.Extensions.Caching.Memory. Distributed caching infrastructure, web hosting, or configuration binding. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Console Start here for CLI apps and worker-style entry points that should run through the AppSurface startup pipeline with CliFx. dotnet package add ForgeTrust.AppSurface.Console ConsoleStartup, ConsoleApp, hosted command execution, and CliFx command discovery through AppSurface modules. ASP.NET Core hosting, OpenAPI surfaces, or Razor-based UI composition. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Dependency.Autofac Add this when you need Autofac-specific registrations or container features instead of the default .NET service collection. dotnet package add ForgeTrust.AppSurface.Dependency.Autofac AppSurfaceAutofacModule and Autofac-aware service registration hooks for AppSurface modules. The default Microsoft DI container, web hosting, or command hosting by itself. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Aspire Start here for .NET Aspire app-model projects that want AppSurface-style modular composition for service defaults and distributed resources. dotnet package add ForgeTrust.AppSurface.Aspire AspireApp entry points and modular registration for distributed application resources and service defaults. ASP.NET Core web hosting, Razor UI features, or the standalone docs host. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web Install this first for a normal ASP.NET Core app with AppSurface modules when you want the base web startup pipeline before layering on optional UI or docs packages. dotnet package add ForgeTrust.AppSurface.Web Base ASP.NET Core hosting, middleware and endpoint composition, conventional browser error-page hooks, and the core AppSurface web module contract. OpenAPI generation, Scalar UI, RazorWire reactive UI, Tailwind build integration, or the RazorDocs host. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.OpenApi Add this after the base web package when you want generated OpenAPI endpoints for an AppSurface web app. dotnet package add ForgeTrust.AppSurface.Web.OpenApi AddOpenApi wiring, endpoint explorer setup, endpoint mapping, and default OpenAPI document transforms. A hosted API reference UI or reactive Razor components. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.Scalar Add this after OpenAPI when you want Scalar's interactive API reference UI served by your AppSurface web app. dotnet package add ForgeTrust.AppSurface.Web.Scalar Scalar UI endpoint mapping and the OpenAPI module dependency needed to feed it. OpenAPI authoring by itself without the base web host, or reactive Razor component streaming. Package README public preview
commercial ready
notes
ForgeTrust.RazorWire Add this when you want reactive Razor fragments, Turbo-style page updates, server-sent streams, or islands without moving to a separate frontend app. dotnet package add ForgeTrust.RazorWire RazorWire modules, TagHelpers, stream helpers, Razor fragment updates, and hybrid island support. OpenAPI generation, API reference UI, or Tailwind asset compilation. Package README public preview
commercial ready
notes
ForgeTrust.AppSurface.Web.Tailwind Add this when you want Tailwind build and watch integration in an AppSurface web app without carrying a Node.js asset pipeline. dotnet package add ForgeTrust.AppSurface.Web.Tailwind Tailwind standalone CLI integration, watch mode, generated CSS output, and transitive runtime package selection for supported build hosts. JavaScript plugin ecosystems that require npm-first tooling, or direct runtime-package selection. Package README public preview
commercial ready
notes

Support and proof-host surfaces

Support and runtime packages

  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.linux-arm64: Tailwind standalone runtime for Linux Arm64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.linux-x64: Tailwind standalone runtime for Linux x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.osx-arm64: Tailwind standalone runtime for macOS Arm64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.osx-x64: Tailwind standalone runtime for macOS x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.
  • ForgeTrust.AppSurface.Web.Tailwind.Runtime.win-x64: Tailwind standalone runtime for Windows x64 build hosts. Restore it transitively through ForgeTrust.AppSurface.Web.Tailwind instead of installing it directly. Release: support runtime; not applicable; notes.

Docs and proof hosts

  • ForgeTrust.AppSurface.Docs: Reusable docs package for harvesting repository docs into a RazorDocs UI. This is a real package, but it is a proof-host surface rather than the default first install for general AppSurface apps. Release: proof host; not applicable; notes. Start here: RazorDocs README
  • ForgeTrust.AppSurface.Docs.Standalone: Thin export host for serving or exporting RazorDocs. Treat it as a proof host and example app, not a package you install into another project. Release: proof host; not applicable; notes. Start here: Standalone host README

Not in the direct-install matrix

  • ForgeTrust.AppSurface.Cli: Planned public appsurface .NET tool. The docs verb owns RazorDocs preview workflows that were previously sketched as a separate razordocs CLI. Release: excluded; not applicable; notes.
  • ForgeTrust.RazorWire.Cli: Held out of the direct-install chooser until issue #171 lands real .NET tool packaging and stable install guidance. Release: excluded; not applicable; notes.

Maintainer notes

  • Edit packages/package-index.yml when the public package story changes.
  • Keep publish_decision and expected_dependency_package_ids in packages/package-index.yml aligned with the package artifact workflow so the chooser and release contract share one package source of truth.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- generate after changing package classifications or package READMEs.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- verify-packages --package-version 0.0.0-ci.local before publishing changes that affect package metadata, project references, or Tailwind runtime payloads.
  • Run dotnet run --project tools/ForgeTrust.AppSurface.PackageIndex/ForgeTrust.AppSurface.PackageIndex.csproj -- gate before publishing rebrand or release metadata changes.
  • Keep packages/README.md.yml hand-authored so RazorDocs metadata, trust-bar copy, and section placement stay intentional.