---
meta:
  version: "v1"
  source: https://superpowers.frontis.nl/conventions/umbraco-packages.yaml
  snapshotDate: 2026-06-11
  description: >
    Catalog of reusable Frontis NuGet packages for Umbraco projects.
    Coding agents must check this catalog before building functionality
    in a Frontis Umbraco project: prefer an existing Frontis package over
    custom code. Packages are developed in the Frontis Umbraco base
    project repository (adapters folder) and published to the private
    Frontis feed. Versions follow the Umbraco major (17.x) unless the
    package is Umbraco-independent, in which case they follow the .NET
    major (10.x) or their own semver.

feed:
  name: Frontis
  url: https://pkgs.dev.azure.com/frontisbv/_packaging/Frontis/nuget/v3/index.json
  packageSourceMapping: "Frontis.*"
  note: >
    nuget.config in Frontis Umbraco projects maps Frontis.* to this feed
    and everything else to nuget.org. Do not change the mapping.

rules:
  - Prefer an existing Frontis package over building custom functionality.
  - Register packages via their IUmbracoBuilder extension in Program.cs.
  - Configure packages under the documented configuration section.
  - Keep all versions in Directory.Packages.props (central package management).
  - Propose extracting generic reusable functionality into a new adapter
    package in the base project instead of leaving it in a customer project.

packages:
  - id: Frontis.Umbraco.WebCommon
    versioning: umbraco-major
    purpose: >
      Common web setup for Umbraco sites: Application Insights, Azure Blob
      media storage, cache-control middleware, URL rewriting and redirects,
      security headers and CSP, CORS, Cloudflare forwarded headers, SSL
      helper, ImageSharp parallelism restriction.
    registration: ".AddCommonWebModule() on IUmbracoBuilder; UseFrontisSSL(), UseFrontisCloudflare(), UseFrontisCors(), RestrictParallelismForImageCropping() on the host builder; UseSecurityPolicy(), UseRewriter() in the pipeline"
    configSections: ["ContentSecurityPolicy", "Frontis:Redirect", "Frontis:Rewrites", "Frontis:Cors"]

  - id: Frontis.Umbraco.BlockList
    versioning: umbraco-major
    purpose: >
      Renders Umbraco Block List items via strongly typed ViewComponents
      (BlockListViewComponentBase<TContent, TSettings, TViewModel>) with
      automatic block discovery through assembly scanning.
    registration: ".AddFrontisBlocklist([typeof(Program).Assembly]) on IUmbracoBuilder; render with <vc:block-list model=\"...\" />"
    notes: "Views at /BlockList/Blocks/{Name}/BlockList{Name}.cshtml; requires /BlockList/Views/BlockList.cshtml wrapper view."

  - id: Frontis.Umbraco.BackofficeAuthentication
    versioning: umbraco-major
    purpose: >
      Azure AD (Entra ID) login for the Umbraco backoffice via OAuth 2.0
      with auto-linking by email. Kept as a package so security fixes ship
      as NuGet updates.
    registration: ".AddAzureADBackofficeAuthentication() on IUmbracoBuilder + App_Plugins folder"
    configSections: ["AzureAd:UserLoginSettings"]

  - id: Frontis.Umbraco.Search
    versioning: umbraco-major
    purpose: >
      Extends Examine-based Umbraco search: enriched indexing of nested
      content and Block List/Grid, culture-specific indexing, query
      sanitization, hit highlighting and a multi-index searcher, driven
      by a searchindex.json field configuration.
    registration: ".AddSearchModule() on IUmbracoBuilder"
    configSections: ["Frontis:Search"]

  - id: Frontis.Umbraco.Search.Indexer
    versioning: umbraco-major
    purpose: >
      Generates the searchindex.json for Frontis.Umbraco.Search from the
      current document types so the search field setup is not manual.
    registration: "services.AddSearchIndexer(); then GET /umbraco/management/api/v1/SearchIndexer while logged into the backoffice"

  - id: Frontis.Umbraco.TagHelpers
    versioning: umbraco-major
    purpose: >
      Razor TagHelpers: <fr-fontawesome> icons with global defaults,
      dictionary translation tag helper with fallback languages, and a
      selected-option tag helper for forms.
    registration: ".AddTagHelpers() on IUmbracoBuilder"
    configSections: ["Frontis:TagHelpers"]

  - id: Frontis.StructuredLogging
    versioning: dotnet-major
    purpose: >
      Automatic structured exception logging: StructuredLoggingException
      base class with message templates, ExceptionContext attribute,
      ILogger.AutoLog(ex), and an ApiExceptionFilter mapping exceptions to
      HTTP status codes. Works in any ASP.NET Core app.
    registration: "builder.Services.AddControllers(o => o.Filters.Add<ApiExceptionFilter>())"

  - id: Frontis.Umbraco.Mjml
    versioning: umbraco-major
    purpose: >
      MJML-based responsive email templates defined in Razor, converted to
      HTML and sent via Umbraco SMTP settings, with attachments and custom
      data models.
    registration: ".AddMjml() on IUmbracoBuilder"

  - id: Frontis.Umbraco.MemberAccounts
    versioning: umbraco-major
    purpose: >
      Default Umbraco member flows: login, registration with mandatory
      email verification, forgot-password. Auto-creates the MemberAccount
      doctype/template on startup.
    registration: ".AddMjml() first, then .AddMemberAccounts() on IUmbracoBuilder; override views by creating same-path views (e.g. /Components/MemberAccounts/LoginForm/LoginForm.cshtml)"

  - id: Frontis.Umbraco.Forms
    versioning: umbraco-major
    purpose: >
      Umbraco Forms package shipping the Frontis Tailwind theme
      (FrontisTailwindTheme).
    registration: "automatic via composer; no manual call needed"

  - id: Frontis.Umbraco.Localizations.Api
    versioning: umbraco-major
    purpose: >
      Localization/dictionary management API for Umbraco with a caching
      layer: all dictionary items per locale, single items by key, items
      with descendants.
    registration: ".AddLocalizationsApi() on IUmbracoBuilder"

  - id: Frontis.Umbraco.PDFGenerator
    versioning: umbraco-major
    purpose: >
      HTML-to-PDF conversion through the Frontis EvoPdf web service,
      including merged documents and headers/footers. No Umbraco
      dependency despite the name.
    registration: "builder.Services.AddPDFGenerator(builder.Configuration)"
    configSections: ["Frontis:PDF"]

  - id: Frontis.Umbraco.VisitorContext
    versioning: umbraco-major
    purpose: >
      Cookie/HttpContext-based visitor context (language, country,
      currency) for headless scenarios where variation context is not
      available, with ordered ensurement of dependent properties.
    registration: "services.AddVisitorContext().WithContextProperty<T>(); ensure via IVisitorContextEnsurementService"

  - id: Frontis.Web.NonLiveAccess
    versioning: semver
    purpose: >
      Restricts frontend access on non-live environments via IP allowlist,
      access-key cookie or query parameter.
    registration: "services.AddFrontisNonLiveAccessFilter<TController>(Configuration) + [FrontendAccessFilter] attribute"
    configSections: ["Frontis:NonLiveAccess"]

  - id: Frontis.Umbraco.DocTypeBuilder
    versioning: umbraco-major
    purpose: >
      Programmatically create Umbraco document types during package
      installation with a DTO-based, idempotent API (tabs, property
      groups, element types, templates, multi-culture).
    registration: ".AddDocTypeBuilder() on IUmbracoBuilder; IFrontisDocTypeBuilder.CreateDocTypeAsync(...)"

  - id: Frontis.Umbraco.DocTypeBuilder.Extended
    versioning: umbraco-major
    purpose: >
      Declarative document type and data type definitions initialized at
      application startup, building on DocTypeBuilder.
    registration: ".AddDocTypeBuilderExtended(b => b.WithDocTypeDefinition<T>().WithDataTypeDefinition<T>().InitialzeOnStartup())"

  - id: Frontis.Umbraco.FacetedOverview
    versioning: umbraco-major
    purpose: >
      Faceted search/filtering on Azure Cognitive Search: automatic content
      indexing, dynamic facets via attributes, base controllers/services,
      optional DocTypeBuilder integration.
    registration: ".AddFacetedOverview<TSearchItem, TResultItem, TFacetSettings>(o => o.WithDocTypeBuilder()) on IUmbracoBuilder"
    configSections: ["AzureSearch"]

  - id: Frontis.Umbraco.Feeds
    versioning: umbraco-major
    purpose: >
      XML feed generation with automatic lifecycle: EF Core context on the
      Umbraco database, publish/unpublish notification handlers and
      Hangfire rebuild jobs per feed type.
    registration: ".AddFeeds(f => f.WithFeedType<TFeedItemDto, TIndexer>(\"xmlItemRoot\", docTypeAliases)) on IUmbracoBuilder; implement IFeedIndexer<T>"

  - id: Frontis.Umbraco.MailContent
    versioning: umbraco-major
    purpose: >
      Mail content management in Umbraco with a backoffice dashboard,
      SendGrid integration, mail log with statistics/anonymization, and an
      Umbraco Forms workflow type.
    registration: ".AddMailContent(...) on IUmbracoBuilder"

  - id: Frontis.Umbraco.Commerce
    versioning: umbraco-major
    purpose: >
      Pre-build of Umbraco Commerce with a Frontis layer and headless
      functionality (companion NPM package), extensible through
      IFrontisCommerceEvent hooks. Extensive docs in the Frontis DevOps wiki.
    registration: ".AddFrontisCommerce(...) on IUmbracoBuilder"

  - id: Frontis.Umbraco.PropertyEditors.Heading
    versioning: umbraco-major
    purpose: >
      Property editor separating semantic heading tag (H1-H6/SPAN) from
      visual style, with strongly typed HtmlHeading value converter and a
      backoffice UFM filter for block labels.
    registration: "auto-registers on startup; render via Model.Value<HtmlHeading>() or the <vc:heading> view component"

  - id: Frontis.Umbraco.PropertyEditors.FontAwesomePicker
    versioning: umbraco-major
    purpose: >
      Backoffice property editor for picking Font Awesome icons (families
      and styles), storing the icon name string.
    registration: "static web assets + umbraco-package.json property editor extensions"

  - id: Frontis.Umbraco.UmbracoOpenIdConnectClient
    versioning: umbraco-major
    purpose: >
      Automatic OAuth/OIDC access-token lifecycle management (refresh
      tokens) for typed HTTP clients in Umbraco apps. Successor of
      Frontis.Umbraco.UmbracoAbpClient.
    registration: ".AddUmbracoOpenIdConnectAccessTokenManagement() on IUmbracoBuilder + .AddUmbracoUserAccessTokenHandler() on typed clients"
    configSections: ["ABP"]

  - id: Frontis.Umbraco.DealerModule.Api
    versioning: umbraco-major
    purpose: >
      Dealer/store locator: map locations and categories managed in
      Umbraco, exposed via OData endpoints including nearest-location
      queries, with multiple named configurations.
    registration: ".AddDealerModule() on IUmbracoBuilder"
    configSections: ["Frontis:DealerModule"]

  - id: Frontis.Hangfire
    versioning: dotnet-major
    purpose: >
      Modular Hangfire extensions: failure notifications after final retry
      (Notify), cooperative job timeouts (Timeout), and safe colored
      console output (Color).
    registration: "builder.AddFrontisHangfireNotification() + app.UseFrontisHangfireNotification(); [FrontisHangfireNotify(typeof(...))] on jobs"
    configSections: ["Hangfire:FrontisNotify"]

  - id: Frontis.Hangfire.Notify.Email.Umbraco
    versioning: umbraco-major
    purpose: >
      Email notifier for Frontis.Hangfire.Notify using Umbraco's mail
      layer, with templated HTML failure emails.
    registration: "builder.AddFrontisHangfireEmailUmbracoNotify(); [FrontisHangfireNotify(typeof(UmbracoEmailFailureNotifier))]"
    configSections: ["Hangfire:FrontisNotify:Email"]
