Umbraco CMS
CloudHeartcoreDXPMarketplace
14.latest
14.latest
  • Umbraco CMS Documentation
  • Legacy Documentation
    • Our Umbraco
    • GitHub
  • Release Notes
  • Contribute
  • Sustainability Best Practices
  • Fundamentals
    • Get to know Umbraco
    • Setup
      • Requirements
      • Installation
        • Install using .NET CLI
        • Running Umbraco in Docker using Docker Compose
        • Install using Visual Studio
        • Local IIS With Umbraco
        • Install using Visual Studio Code
        • Installing Nightly Builds
        • Running Umbraco on Linux/macOS
        • Unattended Installs
      • Upgrade your project
        • Version Specific Upgrades
          • Upgrade from Umbraco 8 to the latest version
          • Migrate content to Umbraco 8
          • Minor upgrades for Umbraco 8
          • Upgrade to Umbraco 7
          • Minor upgrades for Umbraco 7
      • Server setup
        • Running Umbraco On Azure Web Apps
        • Hosting Umbraco in IIS
        • File And Folder Permissions
        • Runtime Modes
        • Umbraco in Load Balanced Environments
          • Load Balancing Azure Web Apps
          • Standalone File System
          • Advanced Techniques With Flexible Load Balancing
          • Logging With Load Balancing
    • Backoffice
      • Sections
      • Property Editors
        • Built-in Property Editors
          • Checkbox List
          • Collection
          • Color Picker
          • Content Picker
          • Document Picker
          • DateTime
          • Date
          • Decimal
          • Email Address
          • Eye Dropper Color Picker
          • File Upload
          • Image Cropper
          • Label
          • Markdown Editor
          • Media Picker
          • Member Group Picker
          • Member Picker
          • Multi Url Picker
          • Repeatable Textstrings
          • Numeric
          • Radiobutton List
          • Slider
          • Tags
          • Textarea
          • Textbox
          • Toggle
          • User Picker
          • Block Editors
            • Block Grid
            • Block List
          • Dropdown
          • Rich Text Editor
            • Rich Text Editor Configuration
            • Rich Text Editor Styles
            • Rich Text Editor Plugins
            • Blocks in Rich Text Editor
      • Login
      • Document Blueprints
      • Sidebar
      • Log Viewer
      • Language Variants
      • Settings Dashboards
    • Data
      • Defining Content
        • Default Document Types
        • Document Type Localization
      • Creating Media
        • Default Data/Media Types
      • Members
      • Data Types
        • Default Data Types
      • Scheduled Publishing
      • Using Tabs
      • Users
      • Relations
      • Dictionary Items
      • Content Version Cleanup
    • Design
      • Templates
        • Basic Razor Syntax
        • Razor Cheatsheet
      • Rendering Content
      • Rendering Media
      • Partial Views
      • Stylesheets And JavaScript
    • Code
      • Service APIs
      • Subscribing To Notifications
      • Creating Forms
      • Debugging
        • Logging
      • Source Control
  • Implementation
    • Learn how Umbraco works
    • Routing
      • Controller & Action Selection
      • Execute Request
      • Request Pipeline
    • Custom Routing
      • Adding a hub with SignalR and Umbraco
    • Controllers
    • Data Persistence (CRUD)
    • Composing
    • Integration Testing
    • Nullable Reference Types
    • Services and Helpers
      • Circular Dependencies
    • Unit Testing
  • Customizing
    • Extend and customize the editing experience
    • Project Bellissima
    • Setup Your Development Environment
      • Vite Package Setup
    • Foundation
      • Working with Data
        • Repositories
        • Context API
        • Store
        • States
      • Contexts
        • Property Dataset Context
      • Umbraco Element
        • Controllers
          • Write your own controller
      • Sorting
      • Routes
      • Icons
      • Backoffice Localization
      • Terminology
    • Extension Overview
      • Extension Registry
        • Extension Registration
        • Extension Manifest
      • Extension Types
        • Menu
        • Header Apps
        • Icons
        • Modals
          • Confirm Dialog
          • Custom Modals
          • Route Registration
        • Bundle
        • Kind
        • Backoffice Entry Point
        • Extension Conditions
        • Dashboards
        • Entity Actions
        • Entity Bulk Actions
        • Entity Create Option Action
        • Trees
        • Global Context
        • Section Sidebar
        • Section View
        • Sections
        • Workspace Context
        • Workspace Views
        • Workspace Actions
        • Localization
      • Extension Kind
      • Extension Conditions
      • Custom Extension types
    • Sections & Trees
    • Searchable Trees (ISearchableTree)
    • Property Editors
      • Property Editors Composition
        • Property Editor Schema
        • Property Editor UI
      • Property Value Converters
      • Property Actions
      • Integrate Property Editors
      • Tracking References
      • Content Picker Value Converter Example
      • Property Dataset
      • Integrate Validaction
    • Workspaces
    • Umbraco Package
    • UI Library
  • Extending
    • Build on Umbraco functionality
    • Health Check
      • Health Check Guides
        • Click-Jacking Protection
        • Content Content Security Policy (CSP)
        • Content/MIME Sniffing Protection
        • Cross-site scripting Protection (X-XSS-Protection header)
        • Debug Compilation Mode
        • Excessive Headers
        • Fixed Application Url
        • Folder & File Permissions
        • HTTPS Configuration
        • Notification Email Settings
        • SMTP
        • Strict-Transport-Security Header
    • Language Files & Localization
      • .NET Localization
    • Backoffice Search
    • Creating a Custom Database Table
    • Embedded Media Providers
    • Custom File Systems (IFileSystem)
      • Using Azure Blob Storage for Media and ImageSharp Cache
    • Configuring Azure Key Vault
    • Packages
      • Creating a Package
      • Language file for packages
      • Listing a Package on the Umbraco Marketplace
      • Good practice and defaults
      • Packages on Umbraco Cloud
      • Installing and Uninstalling Packages
      • Maintaining packages
      • Create accessible Umbraco packages
      • Example Package Repository
  • Reference
    • Dive into the code
    • Configuration
      • Basic Authentication Settings
      • Connection strings settings
      • Content Dashboard Settings
      • Content Settings
      • Data Types Settings
      • Debug settings
      • Examine settings
      • Exception filter settings
      • FileSystemProviders Configuration
      • Global Settings
      • Health checks
      • Hosting settings
      • Imaging settings
      • Indexing settings
      • Install Default Data Settings
      • Logging settings
      • Maximum Upload Size Settings
      • Models builder settings
      • NuCache Settings
      • Package Migration
      • Plugins settings
      • Request handler settings
      • Runtime settings
      • Security Settings
      • Serilog settings
      • Type finder settings
      • Unattended
      • Web routing
    • Templating
      • Models Builder
        • Introduction
        • Configuration
        • Builder Modes
        • Understand and Extend
        • Using Interfaces
        • Tips and Tricks
      • Working with MVC
        • Working with MVC Views in Umbraco
        • View/Razor Examples
        • Using MVC Partial Views in Umbraco
        • Using View Components in Umbraco
        • Querying & Traversal
        • Creating Forms
      • Macros
    • Querying & Models
      • IMemberManager
      • IPublishedContentQuery
      • ITagQuery
      • UDI Identifiers
      • UmbracoContext helper
      • UmbracoHelper
      • IPublishedContent
        • IPublishedContent Collections
        • IPublishedContent IsHelpers
        • IPublishedContent Property Access & Extension Methods
    • Routing & Controllers
      • Custom MVC controllers (Umbraco Route Hijacking)
      • Custom MVC Routes
      • Custom Middleware
      • URL Rewrites in Umbraco
      • Special Property Type aliases for routing
      • URL Redirect Management
      • Routing in Umbraco
        • FindPublishedContentAndTemplate()
        • IContentFinder
        • Inbound request pipeline
        • Outbound request pipeline
        • Published Content Request Preparation
      • Surface controllers
        • Surface controller actions
      • Umbraco API Controllers
        • Porting old Umbraco API Controllers
    • Content Delivery API
      • Custom property editors support
      • Extension API for querying
      • Media Delivery API
      • Protected content in the Delivery API
      • Output caching
      • Property expansion and limiting
      • Additional preview environments support
    • Webhooks
      • Expanding Webhook Events
    • API versioning and OpenAPI
    • Searching
      • Examine
        • Examine Management
        • Examine Manager
        • Custom indexing
        • PDF indexes and multisearchers
        • Quick-start
    • Using Notifications
      • Notification Handler
      • CacheRefresher Notifications Example
      • ContentService Notifications Example
      • Creating And Publishing Notifications
      • Determining if an entity is new
      • MediaService Notifications Example
      • MemberService Notifications Example
      • Sending Allowed Children Notification
      • Umbraco Application Lifetime Notifications
      • EditorModel Notifications
        • Customizing the "Links" box
      • Hot vs. cold restarts
    • Inversion of Control / Dependency injection
    • Management
      • Using Umbraco services
        • Consent Service
        • Media Service
        • Relation Service
        • Content Service
        • Content Type Service
        • Localization Service
        • User Service
    • Plugins
      • Creating Resolvers
      • Finding types
    • Cache & Distributed Cache
      • Accessing the cache
      • ICacheRefresher
      • IServerMessenger
      • Getting/Adding/Updating/Inserting Into Cache
      • Examples
        • Working with caching
    • Response Caching
    • Security
      • API rate limiting
      • BackOfficeUserManager and Events
      • Cookies
      • Replacing the basic username/password check
      • External login providers
      • Locking of Users and password reset
      • Reset admin password
      • Umbraco Security Hardening
      • Umbraco Security Settings
      • Sensitive data
      • Sanitizing the Rich Text Editor
      • Setup Umbraco for a FIPS Compliant Server
      • HTTPS
      • Two-factor Authentication
      • Server-side file validation
    • Scheduling
    • Common Pitfalls & Anti-Patterns
    • API Documentation
    • Debugging with SourceLink
    • Language Variation
    • UmbracoMapper
    • Distributed Locks
    • Management API
      • Setup OAuth using Postman
    • Custom Swagger API
    • Umbraco Flavored Markdown
  • Tutorials
    • Overview
    • Creating a Basic Website
      • Getting Started
      • Document Types
      • Creating Your First Template
      • CSS and Images
      • Displaying the Document Type Properties
      • Creating a Master Template
      • Creating Pages and Using the Master Template
      • Setting the Navigation Menu
      • Articles and Article Items
      • Adding Language Variants
      • Conclusions
    • Creating your First Extension
    • Creating a Custom Dashboard
      • Adding localization to the dashboard
      • Adding functionality to the Dashboard
      • Using Umbraco UI library in the Dashboard
    • Creating a Property Editor
      • Adding configuration to a Property Editor
      • Integrating context with a Property Editor
      • Custom value conversion for rendering
      • Adding server-side validation
        • Default Property Editor Schema aliases
    • Creating a Multilingual Site
    • Add Google Authentication (Users)
    • Add Microsoft Entra ID authentication (Members)
    • Creating Custom Database Tables with Entity Framework
    • The Starter Kit
      • Lessons
        • Customize the Starter Kit
        • Add a Blog Post Publication Date
          • Add a Blog Post Publication Date
          • Add a Blog Post Publication Date
        • Add Open Graph
          • Add Open Graph - Step 1
          • Add Open Graph - Step 2
          • Add Open Graph - Step 3
          • Add Open Graph - Step 4
          • Add Open Graph - Summary
        • Ask For Help and Join the Community
    • Editor's Manual
      • Getting Started
        • Logging In and Out
        • Umbraco Interface
        • Creating, Saving and Publishing Content Options
        • Finding Content
        • Editing Existing Content
        • Sorting Pages
        • Moving a Page
        • Copying a Page
        • Deleting and Restoring Pages
      • Working with Rich Text Editor
      • Version Management
        • Comparing Versions
        • Rollback to a Previous Version
      • Media Management
        • Working with Folders
        • Working with Media Types
        • Cropping Images
      • Tips & Tricks
        • Refreshing the Tree View
        • Audit Trail
        • Notifications
        • Preview Pane Responsive View
        • Session Timeout
    • Multisite Setup
    • Member Registration and Login
    • Custom Views for Block List
    • Connecting Umbraco Forms and Zapier
    • Creating an XML Sitemap
    • Implement Custom Error Pages
    • Create a custom maintenance page
    • Creating a backoffice API
      • Documenting your controllers
      • Adding a custom Swagger document
      • Versioning your API
      • Polymorphic output in the Management API
      • Umbraco schema and operation IDs
      • Access policies
Powered by GitBook
On this page
  • Sample Manifest
  • Root fields
  • Id
  • Name
  • Version
  • Allow Telemetry
  • Allow Public Access
  • Importmap
  • Extensions
  • Package Manifest IntelliSense
  • Adding inline schema
  • Load Package Manifest files
  • Razor Class Library
Edit on GitHub
Export as PDF
  1. Customizing

Umbraco Package

An extension begins with a Package Manifest

A Package is declared via an Umbraco Package Manifest. This describes the Package and declares one or more UI Extensions. The Package Manifest is a JSON file that is stored in the App_Plugins/{YourPackageName} folder. The file is named umbraco-package.json.

Sample Manifest

This is a sample manifest. It is always stored in a folder in App_Plugins/{YourPackageName}, with the name umbraco-package.json. In this example, the package name is SirTrevor and is a text box property Data Type.

Before Umbraco 14, the manifest was declared in a package.manifest file instead of umbraco-package.json. The old format is no longer supported, but you can migrate the contents to the new format.

umbraco-package.json
{
    "id": "My.Nuget.Package",
    "name": "Sir Trevor",
    "version": "1.0.0-beta",
    "extensions": [
        {
            "type": "propertyEditorUi",
            "alias": "Sir.Trevor",
            "name": "Sir Trevor Property Editor UI",
            "element": "/App_Plugins/SirTrevor/SirTrevor.js",
            "meta": {
                "label": "Sir Trevor",
                "propertyEditorSchemaAlias": "Umbraco.TextBox",
                "icon": "icon-code",
                "group": "Pickers"
            }
        }
    ]
}

Root fields

The umbraco-package accept these fields:

{
    "id": "",
    "name": "",
    "version": "",
    "allowTelemetry": true,
    "allowPublicAccess": false,
    "importmap": {
        "imports": {
            "": ""
        },
        "scopes": {
            "": ""
        }
    },
    "extensions": []
}

Id

The unique identifier for your package. This is used to identify your package and should be unique to your package. If you are creating a package that is distributed via NuGet, you should use the NuGet package ID as the ID for your package.

Name

Allows you to specify a friendly name for your package that will be used for telemetry. If no name is specified the name of the folder will be used instead.

Version

Allow Telemetry

With this field, you can control the telemetry of this package, this will provide Umbraco with the knowledge of how many installations use this package.

The default is true.

Also known as: allowPackageTelemetry

Allow Public Access

This field is used to allow public access to the package. If set to true, the package will be available for anonymous usage, for example on the login screen. If set to false, the package will only be available to logged-in users.

Default is false.

Importmap

The importmap field is an object that contains two properties: imports and scopes. This is used to define the import map for the package. The imports property is an object that contains the import map for the package. The scopes property is an object that contains the scopes for the package.

Example

This example shows how to define an import map for a module exported by a package:

umbraco-package.json
{
    "importmap": {
        "imports": {
            "mypackage/services": "/App_Plugins/MyPackage/services/index.js",
        }
    }
}

The imports object contains the import map for the package. The key is the specifier for the module that is being imported, and the value is the URL of the module.

This allows developers to consume modules that are exported by a package without having to know the exact path to the module:

index.js
import { MyService } from 'mypackage/services';

Extensions

The extensions field is an array of UI Extension objects. Each object describes a single UI Extension.

There are three generic fields that are common to all UI Extensions:

  • type - The type of the UI Extension.

  • alias - The alias of the UI Extension. This must be unique.

  • name - The name of the UI Extension.

These are the current types of UI Extensions:

Type
Description

authProvider

appEntryPoint

backofficeEntryPoint

blockEditorCustomView

A custom view for a block in the block editor.

bundle

A bundle is a collection of other manifests that can be loaded together. You would use this in lieu of a backofficeEntryPoint if all you needed was to load extensions through JavaScript.

condition

currentUserAction

A current user action is a button that can be added to the current user view.

dashboard

dashboardCollection

A dashboard collection is a view that can be added to a collection.

dynamicRootOrigin

A dynamic root origin is a dynamic root origin that can be added to the Dynamic Root selector.

dynamicRootQueryStep

A dynamic root query step is a query step that can be added to the Dynamic Root selector.

entityAction

An entity action is a button that can be added to any entity, like a document, media, member, etc. It will be shown in the entity actions menu and in the entity actions menu.

entityBulkAction

An entity bulk action is a button that can be added to the bulk actions menu, which is shown when multiple entities are selected in a collection view.

entryPoint

(Deprecated) Old name for backofficeEntryPoint.

globalContext

granularUserPermissions

A granular user permission is a permission that can be added to a user. It is used to control access to specific parts of the Backoffice.

headerApp

healthCheck

icons

localization

menu

menuItem

A menu item is a component that can be added to a menu.

mfaLoginProvider

modal

monacoMarkdownEditorAction

packageView

A package view is an optional view that can be shown in the "Packages" section of the Backoffice. The user can navigate to this view to see more information about the package and to manage it.

previewAppProvider

A preview app provider is a provider that can be used to provide a preview app for the Save and Preview action on a document.

propertyAction

A property action is a button that can be added to the property actions menu.

propertyEditorSchema

propertyEditorUi

searchProvider

A search provider is a provider that can be used to provide search results for the search bar in the Backoffice.

searchResultItem

A search result item is a component that can be added to the search results.

theme

A theme is a set of styles that can be added to the Backoffice. The user can select their preferred theme in the current user modal.

tinyMcePlugin

treeItem

A tree item that can be added to the tree.

tree

A tree that can be added to a section.

ufmComponent

userProfileApp

A user profile app is a component that can be added to the current user view.

Collections

Type
Description

collection

A collection to show a list of entities (documents, media, members, etc.).

collectionAction

A collection action is a button that can be added to a collection view.

collectionView

A collection view is a view that can be added to a collection.

Stores and repositories

Type
Description

repository

store

itemStore

An item store is a store that can be used to store items. It is used by repositories to store items.

treeStore

A tree store is a store that can be used to store tree data. It is used by tree repositories to store tree data.

Sections

Type
Description

section

sectionRoute

A section route is a route that can be added to a section. It is used to define the URL of the view that is displayed in the main content area of the Backoffice.

sectionSidebarApp

sectionView

Workspaces

Type
Description

workspace

workspaceActionMenuItem

A workspace action menu item is a button that can be added to the workspace action menu.

workspaceAction

workspaceContext

workspaceFooterApp

A workspace footer app is a component that can be added to the workspace footer.

workspaceView

Package Manifest IntelliSense

Make your IDE be aware about the opportunities of the umbraco-package.json by adding a JSON schema. This gives your code editor abilities to autocomplete and knowledge about the format. This helps to avoid mistakes or errors when editing the umbraco-package.json file.

Adding inline schema

Editors like Visual Studio can use the $schema notation in your file.

{
    "$schema": "../../umbraco-package-schema.json",
    "name": ""
}

Hover over any of the properties to see the description of the property. You can also use the Ctrl + Space (Windows/Linux) or CMD + Space (macOS) shortcut to see the available properties.

Load Package Manifest files

Umbraco scans the App_Plugins folder for umbraco-package.json files two levels deep. When found, the packages are loaded into the system.

You may need to restart the application, if you add a new file or modify an existing manifest:

If the runtime mode is Production, the manifests are cached for 30 days or until the application is restarted to improve performance. In other runtime modes, the cache is cleared every 10 seconds.

Razor Class Library

MyProject.Assets.csproj
<PropertyGroup>
    <StaticWebAssetBasePath>App_Plugins/{YourPackageName}</StaticWebAssetBasePath>
</PropertyGroup>
PreviousWorkspacesNextUI Library

Last updated 1 month ago

The version of your package, if this is not specified there will be no version-specific information for your package. This is used for telemetry and to help users understand what version of your package they are using. It is also used for package migrations. The version should follow the format.

Umbraco supports the current specification of the property as outlined on MDN Web Documentation: .

An authentication provider for .

An app entry point is a JavaScript module that is executed when any app is loaded (Login, Installer, Upgrader, and Backoffice). It will never be destroyed. Read more about .

A backoffice entry point is a JavaScript module that is executed when the backoffice is loaded. It will be destroyed when the backoffice is closed or logged out. Read more about .

A condition that can be used to control the visibility of other UI Extensions. Read more about .

A dashboard is a view that can be added to any section. It is displayed in the dashboard view with tabs. Read more about .

A global context is a context instance that is available to all components in the Backoffice. It is used to share state between components and to provide a way to communicate between components. Read more about .

A header app is a component that can be added to the header such as a button or a link. Read more about .

A health check is a check that can be added to the health check dashboard. Read more about the backend side of .

An icon is a set of icons that can be added to the icon picker. Read more in the .

A localization is a set of translations that can be added to the localization service. Read more about in the UI.

A menu is a component that can be added to the menu bar. Read more about .

This type of login provider is the UI component of used to enable/disable the provider.

A modal dialog. Read more about .

A Monaco Markdown Editor action is a button that can be added to the toolbar of the .

A property editor schema is a model that describes a Data Editor and its properties from the backend to the UI. It is used by Property Editor UIs. Read more about .

A property editor UI is a UI component that can be added to content types. It is used to render the UI of a Data Editor. Read more about .

A TinyMCE plugin is a plugin that can be added to the TinyMCE editor. Read more about .

This type of component is a formatter that can be added to the , which is used in property descriptions and advanced labels.

A repository is a class that can be used to interact with a data source. It is used either by context classes or elements directly to interact with the data source. It typically holds a store instance. Read more about .

A store is a context instance that is available to repositories. It is used by repositories to store data. Read more about .

A section is a section that can be added to the navigation bar of the Backoffice like the "Content" or "Media" sections that are built-in. Read more about .

A section sidebar app that can be added to the section sidebar. Read more about .

A section view is a view that can be added to a section. It is displayed in the main content area of the Backoffice. More than one view can be added to a section, and the user can switch between them. In that case, the views are displayed as tabs. Read more about .

A workspace is a component that can be added to an entity type. This is the editor you see, when you edit an entity. Read more about .

A workspace action is a button that can be added to the workspace such as the "Save" button. Read more about .

A workspace context is a context instance that is available to all components in the workspace. It is used to share state between components and to provide a way to communicate between components. Read more about .

A workspace view is a view that can be added to a workspace. It is displayed in the main content area of the workspace. More than one view can be added to a workspace, and the user can switch between them. In that case, the views are displayed as tabs. Read more about .

Read more about in the Backoffice to get a better understanding of the different types of extensions.

You can implement the interface to provide your own package manifest reader. This can be useful if you want to load package manifests from a different location or source.

Umbraco also supports projects that contain static web assets. The umbraco-package.json file can be placed in the wwwroot folder of the RCL project. The package will be loaded when the RCL is referenced by the main project. You must map the web path to App_Plugins in your .csproj file:

Read more about getting set up for Backoffice development in the section.

Semantic Versioning
importmap
Extension Types
IPackageManifestReader
Razor Class Library (RCL)
Customize Backoffice
external login
Entry Points
Entry Points
Conditions
Dashboards
Global Context
Header Apps
Health Checks
Icons article
Localization
Menus
Two-Factor Authentication
Modals
Markdown Property Editor
Property Editors
Property Editors
TinyMCE Plugins
Umbraco Flavoured Markdown
Repositories
Stores
Sections
Section Sidebar Apps
Section Views
Workspaces
Workspace Actions
Workspace Context
Workspace Views