diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index af4a95a927e..e8d3a57171a 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -148,8 +148,8 @@ * [Extend and customize the editing experience](customizing/overview.md) * [Project Bellissima](customizing/project-bellissima.md) * [Setup Your Development Environment](customizing/development-flow/README.md) - * [TypeScript setup](customizing/development-flow/typescript-setup.md) * [Vite Package Setup](customizing/development-flow/vite-package-setup.md) + * [TypeScript setup](customizing/development-flow/typescript-setup.md) * [Extension Overview](customizing/extending-overview/README.md) * [Extension Registry](customizing/extending-overview/extension-registry/README.md) * [Extension Registration](customizing/extending-overview/extension-registry/extension-registry.md) diff --git a/15/umbraco-cms/customizing/development-flow/vite-package-setup.md b/15/umbraco-cms/customizing/development-flow/vite-package-setup.md index 8c4097981a3..6a477957ca0 100644 --- a/15/umbraco-cms/customizing/development-flow/vite-package-setup.md +++ b/15/umbraco-cms/customizing/development-flow/vite-package-setup.md @@ -7,73 +7,69 @@ 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" %} -This guide is based on our **general recommendations** for working with and building extensions for the Umbraco backoffice. - -You can use **any framework or library**, as you are not limited to the mentioned frameworks. +These are general recommendations for working with and building extensions for the Umbraco backoffice. You can use any framework or library of your choice. {% endhint %} -## Getting Started With Vite +## Before You Begin -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. +Make sure to read the [Setup Your Development Environment](./) article before continuing. -{% hint style="info" %} -Before following this guide, read the [Setup Your Development Environment](./) article. -{% endhint %} +## Create a Vite Package + +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: +1. Open your terminal and navigate to the folder where you want to create the new Vite package. +2. Run the following command: ```bash npm create vite@latest ``` -This command will set up your new package and ask you to pick a framework and a compiler. - -3. Enter `Client` as both the **Project Name** and **Package name** when prompted. - -4. Choose **Lit** and **TypeScript** as the framework and language. +This command starts a setup prompt. -{% hint style="info" %} -For this tutorial, it is recommended to use the names given above. However, feel free to choose other names if preferred. -{% endhint %} +For this tutorial, it is recommended to use the names given below. However, feel free to choose other names if preferred. -

Create vite command choices

+3. When prompted: + * Enter **client** as the **Project Name**. + * Enter **client** as the **Package name**. + * Select **Lit** as the framework. + * Select **TypeScript** as the variant. -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. + This creates a new folder called **client** with your project files. {% hint style="info" %} -Alternatively, you can skip the interactive prompts and use this command: +Alternatively, to skip the prompts, use this command: ```typescript -npm create vite@latest Client -- --template lit-ts +npm create vite@latest client -- --template lit-ts ``` -This will create a Vite Package with Lit and TypeScript in a folder called **Client**. {% endhint %} -5. Navigate to the **Client** project folder and install the required packages: +4. Navigate into the new **client** folder and install the packages: ```bash +cd client npm install ``` +{% hint style="warning" %} Before proceeding, 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](https://www.npmjs.com/package/@umbraco-cms/backoffice). +{% endhint %} -6. Install the Backoffice package using the following command: +5. Install the Umbraco Backoffice package: ```bash npm install -D @umbraco-cms/backoffice ``` -{% hint style="info" %} -To avoid installing Umbraco’s sub-dependencies such as TinyMCE and Monaco Editor, you can add the `--legacy-peer-deps` flag: -{% endhint %} +6. To avoid installing additional dependencies such as TinyMCE or Monaco Editor,use the `--legacy-peer-deps` flag: ```bash npm install --legacy-peer-deps -D @umbraco-cms/backoffice ``` -Using this flag will disable Intellisense for external references. +This disables IntelliSense for external references but keeps the install lean. 7. Open the `tsconfig.json` file. 8. Add the array `types` inside `compilerOptions`, with the entry of `@umbraco-cms/backoffice/extension-types`: @@ -89,7 +85,7 @@ Using this flag will disable Intellisense for external references. } ``` -9. Create a new file called `vite.config.ts` in the folder and insert the following code: +9. Create a new `vite.config.ts` file in the **client** folder: {% code title="vite.config.ts" lineNumbers="true" %} ```ts @@ -101,31 +97,27 @@ export default defineConfig({ entry: "src/my-element.ts", // your web component source file formats: ["es"], }, - outDir: "../App_Plugins/Client", // all compiled files will be placed here + outDir: "../App_Plugins/client", // all compiled files will be placed here emptyOutDir: true, sourcemap: true, rollupOptions: { external: [/^@umbraco/], // ignore the Umbraco Backoffice package in the build }, }, - base: "/App_Plugins/Client/", // the base path of the app in the browser (used for assets) + base: "/App_Plugins/client/", // the base path of the app in the browser (used for assets) }); ``` {% endcode %} -{% hint style="info" %} -The `outDir` parameter specifies where the compiled files are placed. In this example, they are stored in the `App_Plugins/Client` folder. If you are working with a different structure, such as a Razor Class Library (RCL) project, update this path to `wwwroot`. -{% endhint %} +The `outDir` parameter specifies where the compiled files are placed. In this example, they are stored in the `App_Plugins/client` folder. If you are working with a different structure, such as a Razor Class Library (RCL) project, update this path to `wwwroot`. 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. -{% hint style="info" %} The `build:lib:entry` parameter can accept an array which will allow you to export multiple files during the build. You can read more about [Vite's build options here](https://vitejs.dev/config/build-options.html#build-lib). -{% endhint %} -Build the `ts` file in the `Client` folder so we can use it in our package: +10. Build the `ts` file in the **client** folder: ```bash npm run build @@ -133,12 +125,14 @@ npm run build ## Watch for changes and build -If you like to continuously work on the package and have each change built, you can 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: +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: {% code title="package.json" lineNumbers="true" %} ```json { - "name": "Client", + "name": "client", ... "scripts": { "watch": "vite build --watch" @@ -148,15 +142,15 @@ If you like to continuously work on the package and have each change built, you ``` {% endcode %} -Then in the terminal, you can run `npm run watch`. +Run `npm run watch` in the terminal. ## 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. +Declare your package to Umbraco via a file called `umbraco-package.json`. This should be added at the root of your package. The `umbraco-package.json` file should be located at `/App_Plugins/` or `/App_Plugins/{YourPackageName}` for Umbraco to detect it. This example declares a Dashboard as part of your Package, using the Vite example element. -{% code title="Client/public/umbraco-package.json" lineNumbers="true" %} +{% code title="client/public/umbraco-package.json" lineNumbers="true" %} ```json { "$schema": "../../umbraco-package-schema.json", @@ -167,7 +161,7 @@ This example declares a Dashboard as part of your Package, using the Vite exampl "type": "dashboard", "alias": "My.Dashboard.MyExtension", "name": "My Dashboard", - "element": "/App_Plugins/Client/client.js", + "element": "/App_Plugins/client/client.js", "elementName": "my-element", "meta": { "label": "My Dashboard", @@ -194,9 +188,9 @@ Learn more about the abilities of the manifest file in the [Umbraco Package Mani #### Testing your package -To be able to test your package, you will need to run your site. +To test your package, 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. +Before doing this, make sure to run `npm run build` to compile your TypeScript files and copy them to the `App_Plugins/client` folder. {% hint style="warning" %} If you try to include some of these resources via Visual Studio (VS), then make sure not to include TypeScript files. Otherwise, VS will try to include a few lines on your `.csproj` file to compile the TypeScript code that exists in your project folder. When you run your website, VS will try to compile these files and fail. @@ -206,7 +200,7 @@ The final result looks like this:

My dashboard

-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: +In the `src/my-element.ts` file, 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: ```css button {