This article will take you through setting up everything you need to start building extensions and packages for Umbraco.

Required Software

Make sure you have followed the requirements article, especially having installed the following on your machine:

• .NET 8

• Node.js version 20.15.0 (LTS) and higher

Package Setup

App_Plugins

Extensions such as JavaScript, CSS, and manifests, will go into a folder called App_Plugins. If you do not have this folder, you can create it at the root of your Umbraco project.

Source Code

The source code for your extensions should ideally be placed in a different project. You can make great use of a Razor Class Library (RCL) with static assets for this purpose. This will make it easier to maintain and test your code. You can create a new project in the root of your Umbraco project, or you can create a new project in a separate folder.

Bundling

If you are using a bundler like Webpack or Vite, you can configure it to output its files to a folder that Umbraco can see. If you have put your files directly in Umbraco project, you need to copy the compiled files over to the App_Plugins folder.

With a Razor Class Library (RCL) project, you should instead configure your bundler to copy the files over to the wwwroot folder. You can then map your RCL project back to the App_Plugins web path, so Umbraco can read your files. You can do this by setting the StaticWebAssetBasePath in your csproj file:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <StaticWebAssetBasePath>App_Plugins/MyExtension</StaticWebAssetBasePath>
  </PropertyGroup>

</Project>

Dependencies

You can use any package manager you like to install dependencies. We recommend using NPM or Yarn. You can install packages by running the command:

npm install -D <package-name>

This will install the package and save it to your package.json file.

You need to setup a package.json file if you don't have one already. You can do this by running the command:

npm init -y

Umbraco Backoffice

Umbraco publishes an NPM package called @umbraco-cms/backoffice that holds typings and other niceties to build extensions.

You can install this package by running the command:

npm install -D @umbraco-cms/backoffice

This will add a package to your devDependencies containing the TypeScript definitions for the Umbraco Backoffice.

It is important that this namespace is ignored in your bundler. If you are using Vite, you can add the following to your vite.config.ts file:

import { defineConfig } from "vite";

export default defineConfig({
    // other config
    // ...
    // add this to your config
    build: {
        rollupOptions: {
            external: [/^@umbraco/],
        },
    }
});

This ensures that the Umbraco Backoffice package is not bundled with your package.

Read more about using Vite with Umbraco in the Vite Package Setup article.

Visual Studio Code

If you're using Visual Studio Code we recommend the extension called Lit-Plugin to get IntelliSense for Lit Elements and Umbraco UI Library Components.

What's Next?

Now that you have your development environment set up, you can start building your Umbraco extensions. Read more about our recommended setup with Vite to get started.

Umbraco recommends building extensions with a setup using TypeScript and a build tool such as Vite. Umbraco uses the library Lit for building web components which we will use throughout this guide.

Getting Started With Vite

Vite comes with a set of good presets to get you quickly up and running with libraries and languages. For example: Lit, Svelte, and Vanilla Web Components with both JavaScript and TypeScript.

1. Open a terminal and navigate to the project folder where you want to create your new Vite Package.

2. Run the following command in the folder to create a new Vite Package:

This command will help you set up your new package, asking you to pick a framework and a compiler.

1. Enter Client as both the Project Name and Package name when prompted,

1. Choose Lit and TypeScript.

This creates a new folder called Client, sets up our new project, and creates a package.json file, which includes the necessary packages. This is where all your source files live.

1. Navigate to the new project folder Client and install the packages using:

1. Install the Backoffice package using the following command:

1. Create a new file called vite.config.ts in the folder and insert the following code:

This alters the Vite default output into a library mode, where the output is a JavaScript file with the same name as the name attribute in package.json. The name is client.js if you followed this tutorial with no changes.

The source code that is compiled lives in the src folder of your package folder and that is where you can see a my-element.ts file. You can confirm that this file is the one specified as our entry on the Vite config file that we recently created.

Build the ts file in the Client folder so we can use it in our package:

Watch for changes and build

If you like to continuously work on the package and have each change built, you can add a watchscript in your package.json with vite build --watch. The example below indicates where in the structure this change should be implemented:

Then in the terminal, you can run npm run watch.

Umbraco Package declaration

Declare your package to Umbraco via a file called umbraco-package.json. This should be added at the root of your package. In this guide, it is inside the Client/public folder so that Vite automatically copies it over every time it builds.

This example declares a Dashboard as part of your Package, using the Vite example element.

Testing your package

To be able to test your package, you will need to run your site.

Before you do this, you need to make sure to run npm run build to compile your TypeScript files and copy them to the App_Plugins/Client folder.

The final result looks like this:

Back in the src/my-element.ts file, you can update the styles property to make any styling changes. You can change the background-color of the button to white so it is more visible:

Summary

With this, you have set up your Package and created an Extension for the Backoffice.