Setup Your Development Environment

Learn about the recommended development environment to extend Umbraco

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:

• Node.js version 22.15.0 (Long-Term Support) and higher

Use Node Version Manager (NVM) for Windows or Mac/Linux to manage the Node.js versions.

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.

You can include the App_Plugins folder in the wwwroot folder of a Razor Class Library (RCL) project, but it is not required.

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:

MyExtension.csproj

<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

Make sure that you do not install any NPM dependencies directly into the App_Plugins folder. This can cause issues with Build and Publish processes in MSBuild. Always install dependencies in a separate folder and use a bundler to copy the compiled files over to the App_Plugins folder.

TypeScript Setup

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

Ensure that you install the version of the Backoffice package compatible with your Umbraco installation. You can find the appropriate version on the @umbraco-cms/backoffice npm page.

You can install this package by running the command:

npm install -D @umbraco-cms/backoffice@x.x.x

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

TSConfig

Make sure to configure your TypeScript compiler so it includes the Global Types from the Backoffice. This enables you to utilize the declared Extension Types. If your project is using other Packages that provide their Extension Types, list these as well.

In your tsconfig.json file, add the array types inside compilerOptions, with the entry of @umbraco-cms/backoffice/extension-types:

{
    "compilerOptions": {
        ...
        "types": [
            "@umbraco-cms/backoffice/extension-types"
        ]
    }
}

Take extra care when using Vite

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 prepared your development environment, start building your Umbraco extensions. Read the article on Umbraco Extension Template to set all this up.