|
| 1 | +--- |
| 2 | +description: Use the `umbraco-extension` .NET template to create a new Umbraco extension. |
| 3 | +--- |
| 4 | + |
| 5 | +# Umbraco Extension Template |
| 6 | + |
| 7 | +Umbraco provides a .NET template to help you get started with building extensions for the Umbraco backoffice. This template sets up a new project with all the necessary files and configurations to build an extension. The template is called `umbraco-extension` and can be used to create a new Umbraco extension project with a single command. |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | +- [.NET SDK](https://dotnet.microsoft.com/download) version 9.0 or later |
| 11 | +- [Node.js](https://nodejs.org/en/download/) version 22 or later |
| 12 | + |
| 13 | +## Install the Umbraco Extension Template |
| 14 | +To install the Umbraco extension template, run the following command in your terminal: |
| 15 | + |
| 16 | +```bash |
| 17 | +dotnet new install Umbraco.Templates |
| 18 | +``` |
| 19 | + |
| 20 | +This command installs both the `umbraco` and `umbraco-extension` templates, which you can use to create new Umbraco and Umbraco extension projects. If a new Umbraco project has previously been created using `dotnet new umbraco`, the templates may already be installed. |
| 21 | + |
| 22 | +## Create a New Umbraco Extension |
| 23 | +To create a new Umbraco extension project, run the following command in your terminal. It should be executed in a folder where you want to create the new project, for example in the root of your solution: |
| 24 | + |
| 25 | +```bash |
| 26 | +dotnet new umbraco-extension -n MyExtension -ex |
| 27 | +``` |
| 28 | + |
| 29 | +This command creates a new folder called `MyExtension` with the following files and folders: |
| 30 | +- `MyExtension.csproj`: The project file for the extension. |
| 31 | +- `Constants.cs`: A file containing constants for the extension. |
| 32 | +- `Client`: A folder containing the source code for the extension, a `package.json` file, a `tsconfig.json` file, and the `vite.config.ts` configuration file. |
| 33 | +- `README.md`: A readme file with instructions on how to build and run the extension. |
| 34 | + |
| 35 | +The `-ex` flag indicates that you want to include examples of how to use the extension. This flag is optional, but it is recommended to include it if you are new to building extensions for Umbraco. It will additionally give you: |
| 36 | + |
| 37 | +- `Composers`: A folder containing an example composer that registers a custom Swagger API. |
| 38 | +- `Controllers`: A folder containing an example API controller for a dashboard. |
| 39 | +- `Client/src/api`: A folder containing an example API client that calls the API controller. |
| 40 | +- `Client/src/dashboards`: A folder containing an example dashboard Web Component that uses the API client. |
| 41 | + |
| 42 | +After setup, the dashboard appears in the main **Content** section of the Backoffice. |
| 43 | + |
| 44 | +### Add the Extension to an Umbraco Project |
| 45 | + |
| 46 | +To include the extension in your Umbraco project, you need to add a reference to the extension project in your Umbraco project. |
| 47 | + |
| 48 | +#### Option 1: Via Visual Studio |
| 49 | + |
| 50 | +1. Right-click the **Dependencies** node in the Umbraco project. |
| 51 | +2. Select **Add Reference**. |
| 52 | +3. Choose the `MyExtension` project. |
| 53 | +4. Click **OK**. |
| 54 | + |
| 55 | +#### Option 2: Via CLI |
| 56 | +Run the following command in the root folder of your Umbraco project: |
| 57 | + |
| 58 | +```bash |
| 59 | +dotnet add reference ../MyExtension/MyExtension.csproj |
| 60 | +``` |
| 61 | + |
| 62 | +This command adds a reference to the `MyExtension` project in your Umbraco project. You can then build your Umbraco project and see the extension in action. |
| 63 | + |
| 64 | +## Build and Run the Extension |
| 65 | + |
| 66 | +To build and run the extension, install the dependencies and start the Vite development server. To do this, run the following commands in the `Client` folder of your extension project: |
| 67 | + |
| 68 | +```bash |
| 69 | +npm install |
| 70 | +npm run build |
| 71 | +``` |
| 72 | + |
| 73 | +{% hint style="info" %} |
| 74 | +The project also builds automatically when running the Umbraco project. To start the Vite development server in watch mode, run the following command: |
| 75 | + |
| 76 | +```bash |
| 77 | +npm run watch |
| 78 | +``` |
| 79 | +{% endhint %} |
| 80 | + |
| 81 | +This command compiles the TypeScript files and copies them over to the `wwwroot` output folder. Once complete, run the Umbraco project to view the extension in action. |
| 82 | + |
| 83 | +## Publish the Project |
| 84 | + |
| 85 | +The output files are automatically copied to the `wwwroot` folder of your Umbraco project. They are also included in the publishing process when you publish your Umbraco project. You can publish your Umbraco project using the following command: |
| 86 | + |
| 87 | +```bash |
| 88 | +dotnet publish --configuration Release |
| 89 | +``` |
| 90 | + |
| 91 | +## Publish as a Package |
| 92 | + |
| 93 | +To publish your extension as a package, create a NuGet package. Run the following command in the root folder of your extension project: |
| 94 | + |
| 95 | +```bash |
| 96 | +dotnet pack --configuration Release |
| 97 | +``` |
| 98 | + |
| 99 | +This command creates a NuGet package in the `bin/Release` folder of your extension project. You can then publish this package to a NuGet feed or share it with others. |
| 100 | + |
| 101 | +The `umbraco-extension` template is opinionated until a certain point. It is a starting point for building extensions for the Umbraco backoffice. The template includes a basic structure and configuration for building extensions, but you can customize it to fit your needs. You can add additional files, folders, and configurations as needed. |
| 102 | + |
| 103 | +To publish your extension as an Umbraco Package, you need some additional files. For details, see the [Umbraco Package](../../customizing/umbraco-package.md) article. |
| 104 | + |
| 105 | +### The Opinionated Starter Kit |
| 106 | + |
| 107 | +Another option is to use the [Opinionated Umbraco Package Starter Template](https://github.com/LottePitcher/opinionated-package-starter). This is a template that includes all the files and configurations needed to build an Umbraco package. It builds on top of the `umbraco-extension` template and includes additional files and configurations for building Umbraco packages. This template is a great starting point for building Umbraco packages and includes everything you need to get started. |
| 108 | + |
| 109 | +To install this template, run the following command in your terminal: |
| 110 | + |
| 111 | +```bash |
| 112 | +dotnet new install Umbraco.Community.Templates.PackageStarter |
| 113 | +``` |
| 114 | + |
| 115 | +To create a new package project, run the following command: |
| 116 | + |
| 117 | +```bash |
| 118 | +dotnet new umbracopackagestarter -n YourPackageName -an "Your Name" -gu "YourGitHubUsername" -gr "YourGitHubRepoName" |
| 119 | +``` |
0 commit comments