CMS: Adds new article on umbraco-extension

16/umbraco-cms/.gitbook.yaml

@@ -10,4 +10,5 @@ redirects:
     fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/styles: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md
     fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/plugins: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions.md
     fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor-tinymce/blocks: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/blocks.md
-    fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/change-rich-text-editor-ui: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md
+    fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/change-rich-text-editor-ui: fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/README.md
+    customizing/development-flow/typescript-setup: customizing/development-flow/README.md

16/umbraco-cms/customizing/development-flow/README.md

@@ -9,7 +9,7 @@ This article will take you through setting up everything you need to start build
 ## Required Software
 
 Make sure you have followed the [requirements](../../fundamentals/setup/requirements.md) article, especially having installed the following on your machine:
-* [Node.js version 20.15.0 (LTS)](https://nodejs.org/en) and higher
+* [Node.js version 22.15.0 (Long-Term Support)](https://nodejs.org/en) and higher
 
 {% hint style="info" %}
 Use Node Version Manager (NVM) for [Windows](https://github.com/coreybutler/nvm-windows) or [Mac/Linux](https://github.com/nvm-sh/nvm) to manage the Node.js versions.
@@ -19,7 +19,7 @@ Use Node Version Manager (NVM) for [Windows](https://github.com/coreybutler/nvm-
 
 ### 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.
+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 this in the `wwwroot` folder of a Razor Class Library (RCL) project, but it is not required.
 
 ### Source Code
 
@@ -63,7 +63,7 @@ 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.
 {% endhint %}
 
-### Umbraco Backoffice
+### TypeScript Setup
 
 Umbraco publishes an NPM package called `@umbraco-cms/backoffice` that holds typings and other niceties to build extensions.
 
@@ -75,6 +75,25 @@ npm install -D @umbraco-cms/backoffice
 
 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 provides their Extension Types then please list these as well.
+
+In your `tsconfig.json` file. Add the array `types` inside `compilerOptions`, with the entry of `@umbraco-cms/backoffice/extension-types`:
+
+```json
+{
+    "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:
 
 ```ts
@@ -102,4 +121,4 @@ If you're using Visual Studio Code we recommend the extension called [Lit-Plugin
 
 ## 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](vite-package-setup.md) to get started.
+Now that you have prepared your development environment, you can start building your Umbraco extensions. Read the next article on [Umbraco Extension Template](./umbraco-extension-template.md) to set all of this up in one go.

16/umbraco-cms/customizing/development-flow/umbraco-extension-template.md

@@ -0,0 +1,96 @@
+---
+description: Use the `umbraco-extension` dotnet template to create a new Umbraco extension
+---
+
+# Umbraco Extension Template
+
+Umbraco provides a dotnet 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.
+
+## Prerequisites
+- [.NET SDK](https://dotnet.microsoft.com/download) version 9.0 or later
+- [Node.js](https://nodejs.org/en/download/) version 22 or later
+
+## Install the Umbraco Extension Template
+To install the Umbraco extension template, run the following command in your terminal:
+
+```bash
+dotnet new install Umbraco.Templates
+```
+
+This command installs the `umbraco` and `umbraco-extension` templates, which you can use to create new Umbraco and Umbraco extension projects. You may already have this installed, if you have created a new Umbraco project using the `dotnet new umbraco` command.
+
+## Create a New Umbraco Extension
+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:
+
+```bash
+dotnet new umbraco-extension -n MyExtension -ex
+```
+
+This command creates a new folder called `MyExtension` with the following files and folders:
+- `MyExtension.csproj`: The project file for the extension.
+- `Client`: A folder containing the source code for the extension.
+- `tsconfig.json`: The TypeScript configuration file.
+- `vite.config.ts`: The Vite configuration file.
+- `package.json`: The Node.js package configuration file.
+- `README.md`: A readme file with instructions on how to build and run the extension.
+
+### Include the Extension in your Umbraco Project
+
+To include the extension in your Umbraco project, you need to add a reference to the extension project in your Umbraco project. You can do this by right-clicking on the **Dependencies** node in your Umbraco project and selecting **Add Reference**. Then select the `MyExtension` project and click **OK**.
+
+## Build and Run the Extension
+
+To build and run the extension, you need to install the dependencies and start the Vite development server. You can do this by running the following commands in the `Client` folder of your extension project:
+
+```bash
+npm install
+npm run build
+```
+
+{% hint style="info" %}
+The project will also automatically build when you run the Umbraco project. You can also run the Vite development server in watch mode by running the following command:
+
+```bash
+npm run watch
+```
+{% endhint %}
+
+This command compiles the TypeScript files and copies them over to the output folder in `wwwroot`. You can then run your Umbraco project and see the extension in action.
+
+## Publish the Project
+
+The output files should automatically be copied to the `wwwroot` folder of your Umbraco project. They should also be included in the publish process when you publish your Umbraco project. You can publish your Umbraco project using the following command:
+
+```bash
+dotnet publish -c Release
+```
+
+## Publish as a Package
+
+To publish your extension as a package, you need to create a NuGet package. You can do this by running the following command in the root folder of your extension project:
+
+```bash
+dotnet pack -c Release
+```
+
+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.
+
+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.
+
+To publish your extension as an Umbraco Package, you need some additional files. You can read more about that in the [Umbraco Package documentation](../../customizing/umbraco-package.md).
+
+### The Opinionated Starter Kit
+
+One other 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.
+
+You can install this template by running the following command in your terminal:
+
+```bash
+dotnet new install Umbraco.Community.Templates.PackageStarter
+```
+
+Then you can create a new package project by running the following command:
+
+```bash
+dotnet new umbracopackagestarter -n YourPackageName -an "Your Name" -gu "YourGitHubUsername" -gr "YourGitHubRepoName"
+```

16/umbraco-cms/customizing/development-flow/vite-package-setup.md

@@ -7,7 +7,7 @@ description: Get started with a Vite Package, setup with TypeScript and Lit
 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.
 
 {% hint style="info" %}
-These are general recommendations for working with and building extensions for the Umbraco backoffice. You can use any framework or library of your choice.
+These are general recommendations for working with and building extensions for the Umbraco backoffice. You can use any framework or library of your choice. See the [Umbraco Extension Template](./umbraco-extension-template.md) for Umbraco's recommended approach.
 {% endhint %}
 
 ## Before You Begin
@@ -127,7 +127,7 @@ npm run build
 
 ## Watch for changes and build
 
-To continuously work on the package and have each change built, add a `watch`script in your `package.json` with `vite build --watch`. 
+To continuously work on the package and have each change built, add a `watch`script in your `package.json` with `vite build --watch`.
 
 The example below indicates where in the structure this change should be implemented: