readme updates (#18007)

Author: nielslyngsoe

.github/BUILD.md

@@ -36,7 +36,7 @@ In order to build the Umbraco source code locally with Visual Studio Code, first
 
 Open the root folder of the repository in Visual Studio Code.
 
-To build the front end you'll need to open the command pallet (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and run `>Tasks: Run Task` followed by `Client Build`.
+To build the front-end you'll need to open the command pallet (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>) and run `>Tasks: Run Task` followed by `Client Build`.
 
 You can also run the tasks manually on the command line:
 
@@ -46,9 +46,7 @@ npm i
 npm run build:for:cms
 ```
 
-If you just want to watch the UI Client to `Umbraco.Web.UI` then instead of running `build:for:cms`, you can do: `npm run dev:mock`. This will launch the Vite dev server on http://localhost:5173 and watch for changes with mocked API responses.
-
-You can also run `npm run dev:server` to run the Vite server against a local Umbraco instance. In this case, you need to have the .NET project running and accept connections from the Vite server. Please see the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
+If you want to make changes to the UI, you can choose to run a front-end development server. To learn more please read the Umbraco.Web.UI.Client README.md [Run against a local Umbraco instance](../src/Umbraco.Web.UI.Client/.github/README.md#run-against-a-local-umbraco-instance) for more information.
 
 The login screen is a different frontend build, for that one you can run it as follows:
 

src/Umbraco.Web.UI.Client/.github/README.md

@@ -1,42 +1,37 @@
-# Umbraco.Web.UI.Client (Bellissima)
+# Umbraco.Web.UI.Client
 
-This is the working folder for the Umbraco Backoffice client, also known as Bellissima. This is a SPA (Single Page Application) built with Lit.
+This is the Umbraco Backoffice UI/Client, also known as Bellissima.
 
-## Installation instructions
+This is for you as a contributor who likes to make changes to the Backoffice UI/Client project.
 
-1. Run `npm install`
-2. Run `npm run dev` to launch Vite in dev mode
+## Installation
 
-### Environment variables
+1. Make sure you have [NodeJS](https://nodejs.org/en/download) installed.
+2. Run `npm install` to install the dependencies.
 
-The development environment supports `.env` files, so in order to set your own make a copy
-of `.env` and name it `.env.local` and set the variables you need.
+## Ways to run a Development Server
 
-As an example to show the installer instead of the login screen, set the following
-in the `.env.local` file to indicate that Umbraco has not been installed:
+1. If you will be working from VS Code, there is options to run both [back-end and front-end server in debug modes](#debug-via-vs-code).
 
-```bash
-VITE_UMBRACO_INSTALL_STATUS=must-install
-```
+2. Or you can choose to [run each of these individually](#run-a-front-end-server-against-a-local-umbraco-instance), this can be done from the Command-line/Terminal, but requires a few lines from configuration on the back-end server.
 
-## Environments
+### Debug via VS Code
 
-### Development
+If you are using VS Code, you can use the `launch.json` file to start the development server. This will also start the Umbraco instance and open the browser.
 
-The development environment is the default environment and is used when running `npm run dev`. All API calls are mocked and the Umbraco Backoffice is served from the `src` folder.
+You should run the task **Backoffice Launch (Vite + .NET Core)** in the **Run and Debug** panel, which will start the Vite server and the Umbraco instance. It automatically configures Umbraco (using environment variables) to use the Vite server as the Backoffice host. This task will also open a browser window, so you can start developing right away. The first time you run this task, it will take a little longer to start the Umbraco instance, but subsequent runs will be faster. Keep an eye on the Debug Console to see when the Umbraco instance is ready and then refresh the browser.
 
-### Run against a local Umbraco instance
+If you want to run the Vite server only, you can run the task **Backoffice Launch Vite**, which will start the Vite server only and launch a browser.
 
-If you have a local Umbraco instance running, you can use the development environment to run against it by overriding the API URL and bypassing the mock-service-worker in the frontend client.
+If you have an existing Vite server running, you can run the task **Backoffice Attach Vite** to attach the debugger to the Vite server.
 
-Create a `.env.local` file and set the following variables:
+### Run a front-end server against a local Umbraco instance
 
-```bash
-VITE_UMBRACO_API_URL=https://localhost:44339 # This will be the URL to your Umbraco instance
-VITE_UMBRACO_USE_MSW=off # Indicate that you want all API calls to bypass MSW (mock-service-worker)
-```
 
-Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` and add this to the `Umbraco:CMS:Security` section to override the backoffice host:
+To enable the client running on a different server, we need to correct the `appsettings.json` of your project.
+
+For code contributions you can use the backend project of `src/Umbraco.Web.UI`.
+Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` and add these 4 fields to the `Umbraco > CMS > Security`:
 
 ```json
 "Umbraco": {
@@ -51,30 +46,61 @@ Open this file in an editor: `src/Umbraco.Web.UI/appsettings.Development.json` a
 }
 ```
 
-Now start the vite server by running the command: `npm run dev:server` in the `Umbraco.Web.UI.Client` folder, and finally open the http://localhost:5173 URL in your browser.
+This will override the backoffice host URL, enabling the Client to run from a different origin.
 
-### VS Code
+#### Run the front-end server
 
-If you are using VS Code, you can use the `launch.json` file to start the development server. This will also start the Umbraco instance and open the browser.
+Now start the Vite server by running the command: `npm run dev:server` in the `Umbraco.Web.UI.Client` folder.
 
-You should run the task **Backoffice Launch (Vite + .NET Core)** in the **Run and Debug** panel, which will start the Vite server and the Umbraco instance. It automatically configures Umbraco (using environment variables) to use the Vite server as the Backoffice host. This task will also open a browser window, so you can start developing right away. The first time you run this task, it will take a little longer to start the Umbraco instance, but subsequent runs will be faster. Keep an eye on the Debug Console to see when the Umbraco instance is ready and then refresh the browser.
+Finally open `http://localhost:5173` in your browser.
 
-If you want to run the Vite server only, you can run the task **Backoffice Launch Vite**, which will start the Vite server only and launch a browser.
+## Contributing
 
-If you have an existing Vite server running, you can run the task **Backoffice Attach Vite** to attach the debugger to the Vite server.
+If you want to get started on contributing, please read the [contributing guidelines](/.github/contributing-backoffice.md).
+
+A list of issues can be found on the [Umbraco-CMS Issue Tracker](https://github.com/umbraco/Umbraco-CMS/issues). Many of them are marked as `community/up-for-grabs` which means they are up for grabs for anyone to work on.
+
+## Documentation
+
+The documentation can be found on [Umbraco Docs](https://docs.umbraco.com/umbraco-cms).
+
+## Advanced
 
 ### Storybook
 
 You can test the Storybook locally by running `npm run storybook`. This will start the Storybook server and open a browser window with the Storybook UI.
 
 Storybook is an excellent tool to test out UI components in isolation and to document them. It is also a great way to test the responsiveness and accessibility of the components.
 
-## Contributing
+### Front-end server configuration
 
-We accept contributions to this project. However be aware that we are mainly working on a private backlog, so not everything will be immediately obvious. If you want to get started on contributing, please read the [contributing guidelines](/.github/contributing-backoffice.md).
+When running `npm run dev` the default default environment and is used when running. In this case all API calls are mocked and the Umbraco Backoffice is served from the `src` folder.
 
-A list of issues can be found on the [Umbraco-CMS Issue Tracker](https://github.com/umbraco/Umbraco-CMS/issues). Many of them are marked as `community/up-for-grabs` which means they are up for grabs for anyone to work on.
+This section describes how this can be used and how you can make your own configuration.
 
-## Documentation
+#### Environment variables
 
-The documentation can be found on [Umbraco Docs](https://docs.umbraco.com/umbraco-cms).
+You can setup your own environment variables for the development front-end server, which is based on Vite.
+
+The development environment supports `.env` files, so in order to set your own make a copy
+of `.env` and name it `.env.local` and set the variables you need.
+
+As an example to show the installer instead of the login screen, set the following
+in the `.env.local` file to indicate that Umbraco has not been installed:
+
+```bash
+VITE_UMBRACO_INSTALL_STATUS=must-install
+```
+
+#### Run against a local backend server
+
+If you like the default script `npm run dev` to not use mock server and run against a server of your own configuration, this can be done via Environment variables.
+
+Create a `.env.local` file and set the following variables:
+
+```bash
+VITE_UMBRACO_API_URL=https://localhost:44339 # This will be the URL to your Umbraco instance
+VITE_UMBRACO_USE_MSW=off # Indicate that you want all API calls to bypass MSW (mock-service-worker)
+```
+
+This example above, is identical to what happens when running `npm run dev:server`.