Umbraco Package

An extension begins with a Umbraco Package

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

Sample

Here is a sample package. It should be 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.

umbraco-package.json
{
    "id": "My.Nuget.Package",
    "name": "Sir Trevor",
    "version": "1.0.0-beta",
    "allowPackageTelemetry": true,
    "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 accepts these fields:

{
    "id": "",
    "name": "",
    "version": "",
    "allowPackageTelemetry": 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

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 Semantic Versioning format.

Allow Package 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 false.

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.

The 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';

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

Extensions

The extensions field is an array of Extension Manifest objects. Each object describes a single client extension.

Read more about these in the Extension Manifests article.

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

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

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

Umbraco also supports Razor Class Library (RCL) 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:

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

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

Last updated