Umbraco CMS

https://github.com/umbraco/umbraco-cms
Admin
Umbraco is a free and open source .NET content management system helping you deliver delightful...
Tokens:92,998
Snippets:1,324
Trust Score:9.7
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Development Environment

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/CLAUDE.md

Navigate to the client directory and install dependencies before starting the development server.

```bash
cd src/Umbraco.Web.UI.Client && npm install && npm run dev
```

--------------------------------

### Start Development Server

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Starts the development server after all setup steps are completed. This command launches the application in a development mode with live reloading.

```bash
# Start development
npm run dev
```

--------------------------------

### Install Dependencies

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/mocks/tools/sqlite-to-mock/README.md

Installs the necessary npm packages for the tool. Run this command in the project directory.

```bash
npm install
```

--------------------------------

### Copy Example Environment File

Source: https://github.com/umbraco/umbraco-cms/blob/main/MCP.md

Copy the example environment file to your local environment. Customize the `.env.local` file with your specific local settings for Umbraco and MCP integration.

```bash
cp .env.example .env.local
```

--------------------------------

### Run Example Tests

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Executes tests specifically written for project examples. This ensures that the provided examples function as expected.

```bash
# Run example tests
npm run test:examples
```

--------------------------------

### Start Development Server Connected to Real Backend

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Starts the development server and connects it to a live backend API. This is useful for testing frontend changes against actual API responses.

```bash
# Start dev server connected to real backend
npm run dev:server
```

--------------------------------

### Start development server

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/devops/icon-manager/README.md

Commands to launch the icon manager tool for local development.

```bash
npm run dev
```

```bash
npm run dev:icon-manager
```

--------------------------------

### TypeScript with Lit Dashboard Extension Setup

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/README.md

Sets up a new project using Vite with the Lit template for WebComponent development, then installs the Umbraco backoffice package.

```bash
npm create vite@latest -- --template lit-ts my-package
```

```bash
cd my-package
npm install -D @umbraco-cms/backoffice
```

--------------------------------

### Version Range Conversion Logic Examples

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/CLAUDE.md

Examples of how the semver conversion logic transforms input dependency ranges into published peerDependency ranges.

```text
Input:  ^0.85.0    or    0.85.0
Output: >=0.85.0 <1.0.0
```

```text
Input:  ^3.3.1
Output: ^3.3.1    (kept as-is)
```

```text
Input:  3.16.0    (from @tiptap/*)
Output: ^3.16.0
```

--------------------------------

### Install dependencies

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/devops/icon-manager/README.md

Run this command within the icon-manager folder to install required packages.

```bash
npm install
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Installs all necessary project dependencies. This command must be run using npm, as yarn or pnpm may not correctly handle workspaces.

```bash
# Install dependencies (must use npm, not yarn/pnpm due to workspaces)
npm install

# Note: Requires Node >=22.17.1 and npm >=10.9.2
```

--------------------------------

### Install dependencies for Login and Client

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Login/CLAUDE.md

Run these commands to ensure both the Client and Login projects have their dependencies installed, which is required for TypeScript path resolution.

```bash
cd ../Umbraco.Web.UI.Client && npm install
cd ../Umbraco.Web.UI.Login && npm install
```

--------------------------------

### Example: Generate Mock Data

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/mocks/tools/sqlite-to-mock/README.md

An example of how to run the generation script, specifying the SQLite database path and a set alias. This will output files to a specific directory and format them with eslint.

```bash
npm run generate -- /path/to/Umbraco.sqlite my-site
```

--------------------------------

### Start Development Server with Mock Set

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/mocks/tools/sqlite-to-mock/README.md

Starts the Umbraco backoffice development server using a specific mock data set. Ensure the mock set is correctly registered.

```bash
VITE_MOCK_SET=my-site npm run dev
```

--------------------------------

### Install @umbraco-cms/backoffice

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/README.md

Install the backoffice package as a development dependency using npm.

```bash
npm install -D @umbraco-cms/backoffice
```

--------------------------------

### Run Example Tests in Watch Mode

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Runs example tests and automatically re-runs them upon detecting file changes, facilitating rapid iteration on examples.

```bash
# Run example tests in watch mode
npm run test:examples:watch
```

--------------------------------

### Run Example Tests in Browser

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Executes example tests directly within a browser environment, allowing for interactive debugging and verification.

```bash
# Run example tests in browser
npm run test:examples:browser
```

--------------------------------

### Package and Module Directory Structure

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/package-development.md

Example of the recommended file system hierarchy for a package root containing multiple modules.

```text
src/packages/media/          <- package root
├── media/                   <- module (media management)
│   ├── index.ts
│   ├── manifests.ts
│   └── ...
├── imaging/                 <- module (image processing)
│   ├── index.ts
│   ├── manifests.ts
│   └── ...
└── umbraco-package.ts       <- aggregates module manifests + bundle entry point
```

--------------------------------

### Initialize Umbraco Back-Office Environment

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Login/index.html

Imports necessary themes, starts the mock service worker, and loads the main application entry point.

```javascript
import '../Umbraco.Web.UI.Client/node_modules/@umbraco-ui/uui/dist/themes/light.css'; const { startMockServiceWorker } = await import('./src/mocks/index.ts'); await startMockServiceWorker(); await import('./src/index.ts');
```

--------------------------------

### Build backoffice and login assets

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.StaticAssets/CLAUDE.md

Commands to install dependencies and build assets from the respective UI client and login projects.

```bash
# Build backoffice assets (from Umbraco.Web.UI.Client)
cd src/Umbraco.Web.UI.Client
npm install
npm run build:for:cms

# Build login assets (from Umbraco.Web.UI.Login)
cd src/Umbraco.Web.UI.Login
npm install
npm run build
```

--------------------------------

### Start Development Server with Live Reload

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Launches the development server with live reloading enabled, allowing for instant updates in the browser as code changes.

```bash
# Start dev server (with live reload)
npm run dev
```

--------------------------------

### Run Infrastructure Tests

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Infrastructure/CLAUDE.md

Command-line examples for executing tests using dotnet test filters.

```bash
# All Infrastructure tests
dotnet test --filter "FullyQualifiedName~Infrastructure"

# Specific area (e.g., Persistence)
dotnet test --filter "FullyQualifiedName~Infrastructure.Persistence"

# Integration tests only
dotnet test --filter "Category=Integration&FullyQualifiedName~Infrastructure"
```

--------------------------------

### Start Storybook Development Server

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Launches the Storybook development server, which provides an interactive environment for developing and viewing UI components in isolation.

```bash
# Start Storybook dev server
npm run storybook
```

--------------------------------

### Implement Start Item Fallback Logic

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Api.Delivery/CLAUDE.md

Determines the content scope by attempting to resolve a start item provider, falling back to all content if none is found.

```csharp
// Services/ApiContentQueryService.cs:99-112
if (_requestStartItemProviderAccessor.TryGetValue(out IRequestStartItemProvider? requestStartItemProvider))
{
    IPublishedContent? startItem = requestStartItemProvider.GetStartItem();
    // Use descendants of start item
}
return _apiContentQueryProvider.AllContentSelectorOption(); // Fallback to all
```

--------------------------------

### Run Umbraco Web UI Application

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI/CLAUDE.md

Commands to start the application using Kestrel or watch mode for development.

```bash
# Run with Kestrel (recommended)
dotnet run --project src/Umbraco.Web.UI

# Run with watch for auto-reload
dotnet watch --project src/Umbraco.Web.UI

# Run from Visual Studio
# Profile: "Umbraco.Web.UI" (https://localhost:44339)
# Profile: "IIS Express" (http://localhost:11000)
```

--------------------------------

### Pack and Install Local Umbraco Templates

Source: https://github.com/umbraco/umbraco-cms/blob/main/templates/readme.md

Use these commands to pack your local template changes into a NuGet package and install it from a local source. Ensure you uninstall any global templates first and update the package name accordingly.

```bash
# Pack the templates to a local folder
dotnet pack Umbraco.Templates.csproj -c Release --no-build -o "c:\nuget.local"

# Add this folder as a local nuget source 
dotnet nuget add source "c:\nuget.local" --name "local nuget"

# Make sure you don't have the global templates installed
dotnet new uninstall Umbraco.Templates

# Install your version of the templates, having checked/updated the name of the generated .nupkg file
dotnet new install "c:\nuget.local\Umbraco.Templates.XXXX.nupkg"
```

--------------------------------

### Branch Naming Examples

Source: https://github.com/umbraco/umbraco-cms/blob/main/CLAUDE.md

Examples of branch names following the v{major-version}/{type}/{kebab-case-description} format.

```text
v17/bugfix/12345-correct-display-of-pending-migrations
v17/feature/add-webhook-support
v17/improvement/optimize-content-cache
v17/qa/add-media-service-tests
v17/task/update-ef-core-dependency
```

--------------------------------

### ImageSharp URL Examples

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md

Demonstrates various query string parameters for image manipulation, including resizing, cropping, format conversion, and cache busting.

```url
/media/image.jpg?width=800
```

```url
/media/image.jpg?width=800&height=600&mode=crop&rxy=0.5,0.3
```

```url
/media/image.jpg?cc=0.1,0.1,0.1,0.1
```

```url
/media/image.jpg?format=webp&quality=80
```

```url
/media/image.jpg?width=800&v=abc123
```

--------------------------------

### Start Development Server with MSW Mocks

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Initializes the development server using Mock Service Worker (MSW) to intercept and mock API requests. This is the default mode for development.

```bash
# Start dev server with MSW mocks (default)
npm run dev:mock
```

--------------------------------

### Create a Minimal Manifest

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/manifests.md

An example of a dashboard manifest implementation using lazy-loaded elements and conditional rules.

```typescript
const manifest: UmbExtensionManifest = {
  type: 'dashboard',
  alias: 'My.Dashboard.Analytics',
  name: 'Analytics Dashboard',
  element: () => import('./analytics-dashboard.element.js'),
  weight: 100,
  meta: {
    label: 'Analytics',
    pathname: 'analytics',
  },
  conditions: [
    { alias: 'Umb.Condition.SectionAlias', match: 'Umb.Section.Content' },
  ],
};
```

--------------------------------

### Test Naming Convention Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Demonstrates the recommended naming convention for test suites and individual test cases using describe and it blocks.

```typescript
describe('UmbMyComponent', () => {
	describe('initialization', () => {
		it('should create element', async () => {
			// test
		});

		it('should set default properties', async () => {
			// test
		});
	});

	describe('user interactions', () => {
		it('should emit event when button clicked', async () => {
			// test
		});
	});
});
```

--------------------------------

### Published peerDependencies Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/CLAUDE.md

A sample JSON structure showing the final peerDependencies configuration after the cleansing process.

```json
{
	"peerDependencies": {
		"lit": "^3.3.1",
		"rxjs": "^7.8.2",
		"@umbraco-ui/uui": "^2.0.0",
		"monaco-editor": "^0.55.1",
		"@tiptap/core": "^3.16.0",
		"@hey-api/openapi-ts": ">=0.85.0 <1.0.0"
	}
}
```

--------------------------------

### Verify MCP Dev Package Installation

Source: https://github.com/umbraco/umbraco-cms/blob/main/MCP.md

Run this command to verify that the Umbraco MCP development package is installed correctly and accessible. This is useful for troubleshooting MCP server startup issues.

```bash
npx @umbraco-cms/mcp-dev@17 --help
```

--------------------------------

### Context Mocking Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Demonstrates how to mock a context using UmbMockContext, providing a specific context like UMB_AUTH_CONTEXT.

```typescript
import { UmbMockContext } from '@umbraco-cms/internal/test-utils';

const mockContext = new UmbMockContext();
mockContext.provideContext(UMB_AUTH_CONTEXT, mockAuthContext);
```

--------------------------------

### Handle Drag Start Logic

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/src/packages/core/sorter/sorter.angular.txt

Initializes drag operations by setting transforms, resolving data transfer, and attaching event listeners. It also schedules a visual update for the dragged element.

```javascript
currentElement.style.transform = 'translateZ(0)'; // Solves problem with FireFox and ShadowDom in the drag-image.

				if (config.dataTransferResolver) {
					config.dataTransferResolver(event.dataTransfer, currentItem);
				}

				if (config.onStart) {
					config.onStart({ item: currentItem, element: currentElement });
				}

				window.addEventListener('dragover', handleDragMove);
				window.addEventListener('dragend', handleDragEnd);

				// We must wait one frame before changing the look of the block.
				rqaId = requestAnimationFrame(() => {
					// It should be okay to use the same refId, as the move does not or is okay not to happen on first frame/drag-move.
					rqaId = null;
					currentElement.style.transform = '';
					currentElement.classList.add(config.placeholderClass);
				});
```

--------------------------------

### Define a Global Component

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/package-development.md

Example of a reusable custom element that must be registered and exported from the package index.

```typescript
@customElement('umb-feature')
export class UmbFeatureElement extends UmbLitElement {
	render() {
		return html`Feature Element`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		['umb-feature']: UmbFeatureElement;
	}
}
```

--------------------------------

### Build Workspaces

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Executes the build process for all defined workspaces within the project. This command is useful for monorepo setups where multiple packages need to be built.

```bash
# Build workspaces
npm run build:workspaces
```

--------------------------------

### Web Component Unit Test

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Example of a unit test for a web component using @open-wc/testing. It checks for rendering and accessibility.

```typescript
import { fixture, html, expect } from '@open-wc/testing';
import { UmbMyElement } from './my-element.element';

describe('UmbMyElement', () => {
	let element: UmbMyElement;

	beforeEach(async () => {
		element = await fixture(html`<umb-my-element></umb-my-element>`);
	});

	it('should render', () => {
		expect(element).to.exist;
		expect(element.shadowRoot).to.exist;
	});

	it('should be accessible', async () => {
		await expect(element).to.be.accessible();
	});
});
```

--------------------------------

### MSW API Mock Handler

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Example of an MSW HTTP handler for mocking API requests. This intercepts GET requests to '/umbraco/management/api/v1/document/:id' and returns a JSON response.

```typescript
const { http, HttpResponse } = window.MockServiceWorker;

export const handlers = [
	http.get('/umbraco/management/api/v1/document/:id', ({ params }) => {
		return HttpResponse.json({
			id: params.id,
			name: 'Test Document',
		});
	}),
];
```

--------------------------------

### Client-Side Model Mapping Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/data-flow.md

Illustrates how a data source maps a server response to a client-side model. This ensures consistency by standardizing identifiers and property names.

```typescript
// Data source maps server response → client-side model
const model: UmbMyEntityDetailModel = {
    entityType: UMB_MY_ENTITY_ENTITY_TYPE,
    unique: data.id,        // server "id" → client "unique"
};
```

--------------------------------

### Work with Content

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Core/CLAUDE.md

Demonstrates how to use IContentService and ICoreScopeProvider to safely modify and save content.

```csharp
public class MyService
{
    private readonly IContentService _contentService;
    private readonly ICoreScopeProvider _scopeProvider;
    
    public async Task UpdateContentAsync(Guid key)
    {
        using var scope = _scopeProvider.CreateCoreScope();
        
        IContent? content = _contentService.GetById(key);
        if (content == null)
            return;
        
        // Modify content
        content.SetValue("propertyAlias", "new value");
        
        // Save (triggers notifications)
        var result = _contentService.Save(content);
        
        scope.Complete();
    }
}
```

--------------------------------

### Configure Umbraco Startup in Program.cs

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI/CLAUDE.md

Minimal startup configuration using the builder pattern to initialize Umbraco services and middleware.

```csharp
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

builder.CreateUmbracoBuilder()
    .AddBackOffice()
    .AddWebsite()
#if UseDeliveryApi
    .AddDeliveryApi()
#endif
    .AddComposers()
    .Build();

WebApplication app = builder.Build();

await app.BootUmbracoAsync();

app.UseUmbraco()
    .WithMiddleware(u =>
    {
        u.UseBackOffice();
        u.UseWebsite();
    })
    .WithEndpoints(u =>
    {
        u.UseBackOfficeEndpoints();
        u.UseWebsiteEndpoints();
    });

await app.RunAsync();
```

--------------------------------

### Register SQL Server EF Core Components

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Persistence.EFCore.SqlServer/CLAUDE.md

Registers the SQL Server implementations for migration provider and setup services within the dependency injection container.

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddUmbracoEFCoreSqlServerSupport();
}
```

--------------------------------

### Build and Preview Storybook

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Builds the Storybook project and then serves the built static site locally for previewing. This command combines the build and serve steps for Storybook.

```bash
# Build and preview Storybook
npm run storybook:preview
```

--------------------------------

### Run Tests in Development Mode

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Executes tests using a development-specific configuration. This might include different debugging options or test setups compared to the standard test run.

```bash
# Run tests in development mode
npm run test:dev
```

--------------------------------

### TypeScript with Lit Dashboard Extension Implementation

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/README.md

Implements a custom dashboard extension using TypeScript and LitElement. This example shows how to consume contexts and render UI elements within the Umbraco backoffice.

```typescript
// src/my-element.ts
import { LitElement, html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UmbNotificationContext, UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

@customElement('my-element')
export default class MyElement extends UmbElementMixin(LitElement) {
	private _notificationContext?: UmbNotificationContext;

	constructor() {
		super();
		this.consumeContext(UMB_NOTIFICATION_CONTEXT, (_instance) => {
			this._notificationContext = _instance;
		});
	}

	onClick() {
		this._notificationContext?.peek('positive', { data: { message: '#h5yr' } });
	}

	override render() {
		return html`
			<uui-box headline="Welcome">
				<p>A TypeScript Lit Dashboard</p>
				<uui-button look="primary" label="Click me" @click=${() => this.onClick()}>
				</uui-button>
			</uui-box>
		`;
	}
}

declare global {
	interface HTMLElementTagNameMap {
		'my-element': MyElement;
	}
}
```

```json
{
	"name": "My.Package",
	"version": "0.1.0",
	"extensions": [
		{
			"type": "dashboard",
			"alias": "my.custom.dashboard",
			"name": "My Dashboard",
			"js": "/App_Plugins/MyPackage/dist/my-package.js",
			"weight": -1,
			"meta": {
				"label": "My Dashboard",
				"pathname": "my-dashboard"
			},
			"conditions": [
				{
					"alias": "Umb.Condition.SectionAlias",
					"match": "Umb.Section.Content"
				}
			]
		}
	]
}
```

--------------------------------

### TypeScript Type Guard Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/clean-code.md

Use type guards to narrow down types within conditional blocks, improving type safety. This example checks if a value conforms to the UmbContentModel structure.

```typescript
function isContentModel(value: unknown): value is UmbContentModel {
	return typeof value === 'object' && value !== null && 'id' in value;
}

// Usage
if (isContentModel(data)) {
	// TypeScript knows data is UmbContentModel
	console.log(data.id);
}
```

--------------------------------

### Configure Umbraco Startup Flow

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.Common/CLAUDE.md

Initializes Umbraco services and configures the middleware pipeline in Program.cs.

```csharp
// Program.cs
builder.Services.AddUmbraco(webHostEnvironment, config)
    .AddUmbracoCore()
    .AddMvcAndRazor()
    .AddWebComponents()
    .AddUmbracoProfiler()
    .Build();

await app.BootUmbracoAsync();
app.UseUmbraco()
    .WithMiddleware(u => u.UseBackOffice())
    .WithEndpoints(u => u.UseBackOfficeEndpoints());
```

--------------------------------

### Build and Test Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Infrastructure/CLAUDE.md

Commands for building the infrastructure project, running relevant tests, and creating release packages.

```bash
# Build
dotnet build src/Umbraco.Infrastructure

# Test (tests in ../../tests/)
dotnet test --filter "FullyQualifiedName~Infrastructure"

# Pack
dotnet pack src/Umbraco.Infrastructure -c Release
```

--------------------------------

### Preview Production Build

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Serves a production build of the project locally. This command is useful for previewing how the application will behave in a production environment before deployment.

```bash
# Preview production build
npm run preview
```

--------------------------------

### Security Anti-Patterns

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/security.md

Examples of insecure coding practices that introduce vulnerabilities such as XSS and data exposure.

```typescript
// XSS vulnerability
element.innerHTML = userInput;

// Code injection
eval(userCode);

// Exposing sensitive data
console.log('Token:', authToken);

// Storing secrets
localStorage.setItem('apiKey', key);

// Disabling validation
// @ts-ignore
// eslint-disable-next-line

// Trusting user input
const url = userInput; // Could be javascript:alert()
window.location.href = url;
```

--------------------------------

### Build and Test Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Api.Common/CLAUDE.md

Standard CLI commands for building, packing, testing, and auditing dependencies for the project.

```bash
# Build project
dotnet build src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj

# Pack for NuGet
dotnet pack src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj -c Release

# Test via integration tests
dotnet test tests/Umbraco.Tests.Integration/

# Check packages
dotnet list src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj package --outdated
dotnet list src/Umbraco.Cms.Api.Common/Umbraco.Cms.Api.Common.csproj package --vulnerable
```

--------------------------------

### Extend Value Type Map

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/value-type.md

Example of extending the global map with a specific value type constant.

```typescript
export const UMB_BOOLEAN_VALUE_TYPE = 'Umb.ValueType.Boolean' as const;
declare global {
  interface UmbValueTypeMap {
    [UMB_BOOLEAN_VALUE_TYPE]: boolean;
  }
}
```

--------------------------------

### Generate Cache Key

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.PublishedCache.HybridCache/CLAUDE.md

Creates a unique cache key based on the content GUID and preview status.

```csharp
private static string GetCacheKey(Guid key, bool preview)
    => preview ? $"{key}+draft" : $"{key}";
```

--------------------------------

### Development Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Login/CLAUDE.md

Standard npm commands for managing dependencies, building, and running the development server for the login UI.

```bash
cd src/Umbraco.Web.UI.Login

# Install dependencies
npm install

# Run development server with hot reload
npm run dev

# Build for production (outputs to StaticAssets)
npm run build

# Watch mode build
npm run watch

# Preview production build
npm run preview
```

--------------------------------

### Prepare for npm Publish

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Runs pre-packaging scripts, which typically include tasks like building the project and ensuring it's ready for publishing to npm.

```bash
# Prepare for npm publish
npm run prepack
```

--------------------------------

### Login Build Configuration

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.StaticAssets/CLAUDE.md

Defines the directory paths for the Login project and its output assets.

```text
LoginProjectDirectory = ../Umbraco.Web.UI.Login/
LoginAssetsPath = wwwroot/umbraco/login
```

--------------------------------

### Get Supported Image File Types

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md

Dynamically determines the supported image file types based on the ImageSharp configuration.

```csharp
SupportedImageFileTypes = configuration.ImageFormats.SelectMany(f => f.FileExtensions).ToArray();
```

--------------------------------

### Execute Essential Build and Test Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/CLAUDE.md

Use these CLI commands for building the solution, running tests, formatting code, and packaging projects.

```bash
# Build solution
dotnet build

# Run all tests
dotnet test

# Run specific test category
dotnet test --filter "Category=Integration"

# Format code
dotnet format

# Pack all projects
dotnet pack -c Release
```

--------------------------------

### Implement Simple Value Summary Element

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/value-summary.md

Example of a custom element extending UmbValueSummaryElementBase for rendering simple values like booleans.

```typescript
@customElement('umb-boolean-value-summary')
export class UmbBooleanValueSummaryElement extends UmbValueSummaryElementBase<boolean> {
  override render() {
    return html`<umb-icon .name=${this._value ? 'icon-check' : 'icon-wrong'}></umb-icon>`;
  }
}
```

--------------------------------

### Define and Use a Kind Manifest

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/manifests.md

Demonstrates how to define a kind manifest with matching criteria and how an extension references that kind to inherit properties.

```typescript
// Kind definition — has its own alias, matches by type+kind
{
  type: 'kind',
  alias: 'Umb.Kind.EntityAction.Delete',
  matchType: 'entityAction',
  matchKind: 'delete',
  manifest: { /* defaults */ },
}

// Extension using the kind — references 'delete', not the kind alias
{
  type: 'entityAction',
  kind: 'delete',
  alias: 'Umb.EntityAction.Document.Delete',
  meta: { /* overrides */ },
}
```

--------------------------------

### Development Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Login/CLAUDE.md

Use these npm scripts to manage the development lifecycle of the project.

```bash
# Development
npm run dev        # Start dev server
npm run build      # Build to StaticAssets
npm run watch      # Watch mode
```

--------------------------------

### Build Umbraco.Cms.Imaging.ImageSharp2 Project

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Imaging.ImageSharp2/CLAUDE.md

Command to build the ImageSharp 2.x compatibility project.

```bash
dotnet build src/Umbraco.Cms.Imaging.ImageSharp2/Umbraco.Cms.Imaging.ImageSharp2.csproj
```

--------------------------------

### Common Development Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/CLAUDE.md

Standard commands for managing the development lifecycle, including testing, building, and linting.

```bash
npm run dev
```

```bash
npm test
```

```bash
npm test -- --files "src/packages/path/to/file.test.ts"
```

```bash
npm run build
```

```bash
npm run lint:fix
```

```bash
npm run check:circular
```

--------------------------------

### Handle Observable Subscription Errors

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/error-handling.md

Manage errors that occur during an observable stream subscription. This example logs the error and sets a user-friendly error message.

```typescript
this._subscription = this._dataSource.asObservable().subscribe({
	next: (value) => this._data = value,
	error: (error) => {
		console.error('Observable error:', error);
		this._errorMessage = 'Failed to load data';
	},
	complete: () => console.log('Observable completed'),
});
```

--------------------------------

### TypeScript Class Encapsulation Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/clean-code.md

Demonstrates encapsulation in a LitElement class, distinguishing between public API, private state, private fields, and private methods.

```typescript
export class UmbMyElement extends LitElement {
	// Public API - reactive properties
	@property({ type: String })
	value = '';

	// Private state
	@state()
	private _loading = false;

	// Private fields (not reactive)
	#controller = new UmbMyController(this);

	// Private methods
	private _loadData() { }
}
```

--------------------------------

### Manage EF Core Migrations via CLI

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Persistence.EFCore/CLAUDE.md

Commands for adding, removing, and scripting migrations for SQL Server and SQLite providers. Ensure a valid connection string is configured in appsettings.json before execution.

```bash
# Add migration (SQL Server)
dotnet ef migrations add %MigrationName% -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer -c UmbracoDbContext

# Add migration (SQLite)
dotnet ef migrations add %MigrationName% -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.Sqlite -c UmbracoDbContext

# Remove last migration (SQL Server)
dotnet ef migrations remove -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer

# Remove last migration (SQLite)
dotnet ef migrations remove -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.Sqlite

# Generate migration script
dotnet ef migrations script -s src/Umbraco.Web.UI -p src/Umbraco.Cms.Persistence.EFCore.SqlServer
```

--------------------------------

### Runtime State Check in UmbracoExamineIndex

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Examine.Lucene/CLAUDE.md

This method checks if the Umbraco runtime is in a state that allows indexing. It prevents indexing operations during installation or upgrade phases.

```csharp
protected bool CanInitialize()
{
    var canInit = _runtimeState.Level == RuntimeLevel.Run;
    // Logs warning once if runtime not ready
}
```

--------------------------------

### Enable Authorization Code Flow with PKCE

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Api.Common/CLAUDE.md

Configures the authentication flow to require Proof Key for Code Exchange (PKCE) and allow refresh tokens.

```csharp
// Enable authorization code flow with PKCE
options
    .AllowAuthorizationCodeFlow()
    .RequireProofKeyForCodeExchange()
    .AllowRefreshTokenFlow();
```

--------------------------------

### Umbraco Website Startup Configuration

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.Website/CLAUDE.md

Configure the Umbraco builder and application pipeline to include website and member identity features. Ensure this is called during application startup.

```csharp
builder.CreateUmbracoBuilder().AddWebsite().AddMembersIdentity().Build();
app.UseUmbraco().WithMiddleware(u => u.UseWebsite()).WithEndpoints(u => u.UseWebsiteEndpoints());
```

--------------------------------

### Manage NuGet Package Versions

Source: https://github.com/umbraco/umbraco-cms/blob/main/CLAUDE.md

Demonstrates the separation between project-level references and centralized version definitions in Directory.Packages.props.

```xml
<!-- Individual projects reference WITHOUT version -->
<PackageReference Include="Microsoft.AspNetCore.OpenApi" />

<!-- Versions defined in Directory.Packages.props -->
<PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
```

--------------------------------

### Generate Server API Client

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/data-flow.md

Run this command to generate typed service classes and models from the OpenAPI specification. The output is placed in `src/packages/core/backend-api/`.

```bash
npm run generate:server-api
```

--------------------------------

### SQL Server Azure Detection

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Persistence.SqlServer/CLAUDE.md

Demonstrates how Azure SQL Database is detected using the ServerVersion?.IsAzure property.

```csharp
ServerVersion?.IsAzure
```

--------------------------------

### Entity Action Extension Definition

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/entities.md

Example of defining an entity action extension, specifying its type, kind, alias, and the entity types it supports. Actions are filtered based on `forEntityTypes`.

```typescript
{
  type: 'entityAction',
  kind: 'delete',
  alias: 'Umb.EntityAction.Document.Delete',
  forEntityTypes: [UMB_DOCUMENT_ENTITY_TYPE],
  meta: { /* ... */ },
}
```

--------------------------------

### Set up Store and Context for State Management

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/agentic-workflow.md

Establish state management using UmbStoreBase and UmbContextToken. Define a context class that utilizes the repository and store for managing application state.

```typescript
// 4. State management
export class UmbMyStore extends UmbStoreBase {
	// Observable state
}

export const UMB_MY_CONTEXT = new UmbContextToken<UmbMyContext>('UmbMyContext');

export class UmbMyContext extends UmbControllerBase {
	#repository = new UmbMyRepository();
	#store = new UmbMyStore(this);

	// Public API
}
```

--------------------------------

### Defining Document Entity Types

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/entities.md

Example of defining entity type constants and their corresponding TypeScript types within a domain package. Follows conventions for clarity and type safety.

```typescript
// src/packages/documents/documents/entity.ts
export const UMB_DOCUMENT_ENTITY_TYPE = 'document';
export const UMB_DOCUMENT_ROOT_ENTITY_TYPE = 'document-root';

export type UmbDocumentEntityType = typeof UMB_DOCUMENT_ENTITY_TYPE;
export type UmbDocumentRootEntityType = typeof UMB_DOCUMENT_ROOT_ENTITY_TYPE;
```

--------------------------------

### Run Integration Tests and Verify OpenAPI

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Api.Common/CLAUDE.md

Commands to execute integration tests and verify the generated OpenAPI schema via the Swagger UI.

```bash
# Run integration tests that exercise this library
dotnet test tests/Umbraco.Tests.Integration/

# Verify OpenAPI generation
# 1. Run the application: dotnet run --project src/Umbraco.Web.UI
# 2. Navigate to /umbraco/openapi/ for Swagger UI
# 3. Check schema IDs and operation IDs
# OpenAPI JSON documents available at:
#   - /umbraco/openapi/management.json (Management API)
#   - /umbraco/openapi/delivery.json (Delivery API)
```

--------------------------------

### Build Storybook Documentation

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Compiles the Storybook documentation for the project. This command generates the static assets for viewing the UI components in isolation.

```bash
# Build Storybook documentation
npm run build-storybook
```

--------------------------------

### Test Structure using AAA Pattern

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Shows the Arrange, Act, Assert (AAA) pattern for structuring individual test cases, including setup, action, and verification steps.

```typescript
it('should do something', async () => {
	// Arrange - Set up test data and conditions
	const element = await fixture<UmbMyElement>(html`<umb-my-element></umb-my-element>`);
	const spy = sinon.spy();
	element.addEventListener('change', spy);

	// Act - Perform the action
	element.value = 'new value';
	await element.updateComplete;

	// Assert - Verify the results
	expect(spy.calledOnce).to.be.true;
	expect(element.value).to.equal('new value');
});
```

--------------------------------

### Get Item of Element

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/src/packages/core/sorter/sorter.angular.txt

Retrieves the data model item associated with a given DOM element using a comparison function. Returns null if the element is invalid or no matching item is found.

```javascript
vm.getItemOfElement = function (element) {
				if (!element) {
					return null;
				}
				return scope.model.find((entry) => config.compareElementToModel(element, entry));
			};
```

--------------------------------

### Standard Repository File Structure (Detail, Item)

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/repositories.md

Illustrates the typical file structure for standard detail and item repositories within a feature package.

```treeview
{
package}/{entity}/
├── detail/
│   └── data/
│       ├── {entity}-detail.repository.ts
│       ├── {entity}-detail.server.data-source.ts
│       ├── {entity}-detail.store.ts
│       ├── {entity}-detail.store.context-token.ts
│       ├── manifests.ts
│       └── constants.ts
├── item/                                  # Optional — only if entity needs item lookups
│   └── data/
│       ├── {entity}-item.repository.ts
│       ├── {entity}-item.server.data-source.ts
│       ├── {entity}-item.store.ts
│       ├── {entity}-item.store.context-token.ts
│       └── manifests.ts
}
```

--------------------------------

### Entity Bulk Action Extension Definition

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/entities.md

Example of an entity bulk action extension, which allows operations on multiple selected entities of a specific type. It defines the alias and supported entity types.

```typescript
{
  type: 'entityBulkAction',
  alias: 'Umb.EntityBulkAction.Document.Delete',
  forEntityTypes: [UMB_DOCUMENT_ENTITY_TYPE],
}
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Executes the entire suite of unit tests for the project. This command provides a comprehensive check of the codebase's correctness.

```bash
# Run all unit tests
npm test
```

--------------------------------

### Date and Time Handling with Luxon

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/edge-cases.md

Best practices for date creation, storage, comparison, and validation using the Luxon library.

```typescript
import { DateTime } from '@umbraco-cms/backoffice/external/luxon';

// Create dates
const now = DateTime.now();
const utc = DateTime.utc();
const parsed = DateTime.fromISO('2024-01-15T10:30:00Z');

// Always store dates in UTC
const isoString = now.toUTC().toISO();

// Format for display
const formatted = now.toLocaleString(DateTime.DATETIME_MED);

// Timezone handling
const local = utc.setZone('local');
```

```typescript
// Compare DateTime objects
if (date1 < date2) { }
if (date1.equals(date2)) { }

// Or compare timestamps
if (date1.toMillis() < date2.toMillis()) { }
```

```typescript
const date = DateTime.fromISO(input);
if (!date.isValid) {
	console.error('Invalid date:', date.invalidReason);
	// Handle invalid date
}
```

--------------------------------

### Element Consuming Workspace Context

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/data-flow.md

Consumes context, observes data, renders UI, and dispatches user actions back to the context. This example shows how to bind input changes to the workspace context.

```typescript
import { UMB_MY_ENTITY_WORKSPACE_CONTEXT } from '../my-entity-workspace.context-token.js';
import type { UmbMyEntityDetailModel } from '../../types.js';
import { customElement, html, state, nothing } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('umb-my-entity-workspace-view')
export class UmbMyEntityWorkspaceViewElement extends UmbLitElement {
	@state()
	private _data?: UmbMyEntityDetailModel;

	#workspaceContext?: typeof UMB_MY_ENTITY_WORKSPACE_CONTEXT.TYPE;

	constructor() {
		super();

		this.consumeContext(UMB_MY_ENTITY_WORKSPACE_CONTEXT, (context) => {
			this.#workspaceContext = context;

			this.observe(context.data, (data) => {
				this._data = data;
			});
		});
	}

	#onChange(event: Event) {
		const value = (event.target as HTMLInputElement).value;
		this.#workspaceContext?.setMyProperty(value);
	}

	override render() {
		if (!this._data) return nothing;

		return html`
			<uui-box>
				<umb-property-layout label=${this.localize.term('myEntity_myProperty')}>
					<uui-input
						slot="editor"
						.value=${this._data.myProperty}
						@input=${this.#onChange}></uui-input>
				</umb-property-layout>
			</uui-box>
		`;
	}
}

```

--------------------------------

### Examine Service Auto-Registration

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Examine.Lucene/CLAUDE.md

This C# code illustrates how to automatically register all Examine services, including indexes, using the `AddExamine()` and `AddExamineIndexes()` extension methods. This simplifies the setup process in Umbraco applications.

```csharp
builder
    .AddExamine()
    .AddExamineIndexes();
```

--------------------------------

### Running Tests with npm

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/testing.md

Common npm commands for running tests locally, including watch mode and filtering by file pattern.

```bash
# Run all tests once
npm test

# Run in watch mode
npm run test:watch

# Run with dev config (faster, less strict)
npm run test:dev

# Run in watch mode with dev config
npm run test:dev-watch

# Run specific test file pattern
npm test -- --files "**/my-component.test.ts"
```

--------------------------------

### TypeScript Discriminated Unions Example

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/clean-code.md

Discriminated unions provide a way to model states with different properties, ensuring type safety when handling results or different data shapes. The 'success' property acts as the discriminant.

```typescript
type Result<T> =
	| { success: true; data: T }
	| { success: false; error: Error };

function handleResult<T>(result: Result<T>) {
	if (result.success) {
		console.log(result.data); // TypeScript knows this exists
	} else {
		console.error(result.error); // TypeScript knows this exists
	}
}
```

--------------------------------

### Create a Simple Tiptap Extension

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/src/packages/tiptap/CLAUDE.md

Defines the API, toolbar logic, and manifest registration for a basic Tiptap extension.

```typescript
// bold.tiptap-api.ts
import { Bold } from '../../externals.js';
import { UmbTiptapExtensionApiBase } from '../tiptap-extension-api-base.js';

export default class UmbTiptapBoldExtensionApi extends UmbTiptapExtensionApiBase {
	getTiptapExtensions = () => [Bold];
}

// bold.tiptap-toolbar-api.ts
import { UmbTiptapToolbarElementApiBase } from '../tiptap-toolbar-element-api-base.js';
import type { Editor } from '../../externals.js';

export default class UmbTiptapBoldToolbarApi extends UmbTiptapToolbarElementApiBase {
	override execute(editor?: Editor) {
		editor?.chain().focus().toggleBold().run();
	}
}

// manifests.ts — uses dynamic-import thunks pointing at the SHARED boundary file,
// so manifest registration stays slim and the implementation code is only fetched
// the first time `umb-input-tiptap` actually mounts.
export const manifests: Array<UmbExtensionManifest> = [
	{
		type: 'tiptapExtension',
		alias: 'Umb.Tiptap.Bold',
		name: 'Bold Tiptap Extension',
		api: () => import('../extension-apis.bundle.js').then((m) => ({ default: m.UmbTiptapBoldExtensionApi })),
		meta: {
			icon: 'icon-bold',
			label: 'Bold',
			group: '#tiptap_extGroup_formatting',
		},
	},
	{
		type: 'tiptapToolbarExtension',
		kind: 'button',
		alias: 'Umb.Tiptap.Toolbar.Bold',
		name: 'Bold Tiptap Toolbar Extension',
		api: () => import('../extension-apis.bundle.js').then((m) => ({ default: m.UmbTiptapBoldToolbarApi })),
		forExtensions: ['Umb.Tiptap.Bold'],
		meta: {
			alias: 'bold',
			icon: 'icon-bold',
			label: '#buttons_bold',
		},
	},
];
```

--------------------------------

### TypeScript Utility Types Examples

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/clean-code.md

Leverage built-in TypeScript utility types to create new types based on existing ones. These are useful for making properties optional, picking specific ones, omitting others, or making types immutable.

```typescript
// Partial - Make all properties optional
type PartialContent = Partial<UmbContentModel>;

// Pick - Select specific properties
type ContentSummary = Pick<UmbContentModel, 'id' | 'name' | 'icon'>;

// Omit - Remove specific properties
type ContentWithoutId = Omit<UmbContentModel, 'id'>;

// Readonly - Make immutable
type ReadonlyContent = Readonly<UmbContentModel>;
```

--------------------------------

### Backoffice Build Configuration

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.StaticAssets/CLAUDE.md

Defines the directory paths for the Backoffice project and its output assets.

```text
BackofficeProjectDirectory = ../Umbraco.Web.UI.Client/
BackofficeAssetsPath = wwwroot/umbraco/backoffice
```

--------------------------------

### Essential Development Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI/CLAUDE.md

Common CLI commands for running the development site and resetting runtime data or configuration files.

```bash
# Run development site
dotnet run --project src/Umbraco.Web.UI

# Clean runtime data (reset database)
rm -rf src/Umbraco.Web.UI/umbraco/Data

# Reset to fresh install
rm src/Umbraco.Web.UI/appsettings.json
rm src/Umbraco.Web.UI/appsettings.Development.json
```

--------------------------------

### Essential Build and Maintenance Commands

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Infrastructure/CLAUDE.md

Standard CLI commands for building, testing, formatting, and packaging the Umbraco.Infrastructure project.

```bash
# Build
dotnet build src/Umbraco.Infrastructure

# Test Infrastructure
dotnet test --filter "FullyQualifiedName~Infrastructure"

# Format code
dotnet format src/Umbraco.Infrastructure

# Pack for NuGet
dotnet pack src/Umbraco.Infrastructure -c Release
```

--------------------------------

### Generate TypeScript and Import Maps

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/package-development.md

Run these commands to ensure TypeScript, browser import maps, and test configurations resolve the new package.

```bash
npm i && npm run generate:tsconfig
```

--------------------------------

### Define Configuration

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Core/CLAUDE.md

Creates a settings class and binds it to the Umbraco configuration system within a Composer.

```csharp
// 1. Create settings class in Configuration/Models/
public class MySettings
{
    public string ApiKey { get; set; } = string.Empty;
    public int MaxItems { get; set; } = 10;
}

// 2. Bind in Composer
builder.Services.Configure<MySettings>(
    builder.Config.GetSection("Umbraco:MySettings"));

// 3. Inject via IOptionsMonitor<MySettings>
```

--------------------------------

### Build Project with Vite

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Utilizes Vite as an alternative build tool for compiling the project. This command offers a different build configuration or performance characteristics compared to the default build.

```bash
# Build with Vite (alternative build method)
npm run build:vite
```

--------------------------------

### Build Umbraco Cms Imaging Project

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Imaging.ImageSharp/CLAUDE.md

Builds the ImageSharp integration project for Umbraco CMS.

```bash
dotnet build src/Umbraco.Cms.Imaging.ImageSharp/Umbraco.Cms.Imaging.ImageSharp.csproj
```

--------------------------------

### Project Folder Structure

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Persistence.EFCore.Sqlite/CLAUDE.md

The directory layout for the SQLite EF Core persistence provider.

```text
Umbraco.Cms.Persistence.EFCore.Sqlite/
├── Migrations/
│   ├── 20230622183638_InitialCreate.cs          # No-op (NPoco creates tables)
│   ├── 20230807123456_AddOpenIddict.cs          # OpenIddict tables
│   ├── 20240403141051_UpdateOpenIddictToV5.cs   # OpenIddict v5 schema
│   ├── 20251006140958_UpdateOpenIddictToV7.cs   # OpenIddict v7 (no-op for SQLite)
│   └── UmbracoDbContextModelSnapshot.cs         # Current model state
├── EFCoreSqliteComposer.cs                       # DI registration
├── SqliteMigrationProvider.cs                    # IMigrationProvider impl
├── SqliteMigrationProviderSetup.cs               # IMigrationProviderSetup impl
└── SqliteRetryingExecutionStrategy.cs            # IExecutionStrategy for transient lock errors
```

--------------------------------

### Build Storybook

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Compiles the Storybook project into static assets for deployment or distribution. This command generates the production-ready Storybook.

```bash
# Build Storybook
npm run storybook:build
```

--------------------------------

### Entity Detail Workspace Constructor Arguments

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/workspaces.md

Required configuration object for initializing an entity detail workspace context.

```typescript
{ workspaceAlias: string, entityType: string, detailRepositoryAlias: string }
```

--------------------------------

### Project Directory Structure

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Cms.Api.Common/CLAUDE.md

Visual representation of the project file organization, highlighting key directories like OpenApi, Serialization, and DependencyInjection.

```text
Umbraco.Cms.Api.Common/
├── OpenApi/                    # OpenAPI transformers and schema generators
│   ├── UmbracoSchemaIdGenerator.cs         # Generates schema IDs (e.g., "PagedUserModel")
│   ├── UmbracoOperationIdTransformer.cs    # Generates operation IDs
│   ├── SortTagsAndPathsTransformer.cs      # Sorts OpenAPI tags and paths
│   ├── TagActionsByGroupNameTransformer.cs # Tags operations by controller group
│   ├── FixFileReturnTypesTransformer.cs    # Fixes file return type schemas
│   ├── RequireNonNullablePropertiesSchemaTransformer.cs # Schema nullability
│   └── OpenApiRouteTemplatePipelineFilter.cs # Adds OpenAPI endpoints
├── Serialization/              # JSON type resolution
│   └── UmbracoJsonTypeInfoResolver.cs
├── Configuration/              # Options configuration
│   ├── ConfigureUmbracoOpenApiOptionsBase.cs
│   └── ConfigureOpenIddict.cs
├── DependencyInjection/        # Service registration
│   ├── UmbracoBuilderApiExtensions.cs
│   └── UmbracoBuilderAuthExtensions.cs
├── Builders/                   # RFC 7807 problem details
│   └── ProblemDetailsBuilder.cs
├── ViewModels/Pagination/      # Common DTOs
└── Security/                   # Auth paths and handlers
```

--------------------------------

### Build Project for npm Distribution

Source: https://github.com/umbraco/umbraco-cms/blob/main/src/Umbraco.Web.UI.Client/docs/commands.md

Compiles the project for distribution via npm, including generating type declaration files.

```bash
# Build for npm distribution (with type declarations)
npm run build:for:npm
```
Tokens:
Raw