general-create-workspace

name	general-create-workspace
description	Create a new workspace for an entity in the Umbraco backoffice. Supports two workspace types — default (simple, manifest-only, for root/listing pages) and routable (entity detail editing with create/edit flows). Use when the user says "create a workspace", "add a workspace for X", or "scaffold a workspace". For routable workspaces, the entity must already have a package, entity type, repository, and data source.
allowed-tools	Read, Write, Edit, Grep, Glob

Create Workspace

Create a workspace in the Umbraco backoffice. Two workspace types are available:

• Default workspace — manifest-only, no custom code. For root pages, listing pages, settings.
• Routable workspace — custom context class with create/edit URL routing. For entity detail editing with full CRUD lifecycle.

What you need from the user

1. Workspace type — default (root/listing) or routable (entity detail editing)
2. Entity name — singular, kebab-case (e.g., webhook, data-type, language)
3. Package path — which package directory (e.g., src/packages/webhook/webhook/)

Additional for routable workspaces: 4. Has parent entity — whether creation requires a parent (tree entities like data-type) or not (flat entities like webhook) 5. Entity properties — what observable properties the workspace should expose beyond name and unique

---

Option A: Default Workspace

The simplest workspace. Just a manifest — no custom context class or element. The default kind provides UmbDefaultWorkspaceContext and <umb-default-workspace> automatically.

Prerequisites

• Entity type constant in entity.ts (e.g., UMB_WEBHOOK_ROOT_ENTITY_TYPE)
• Workspace alias constant (e.g., UMB_WEBHOOK_ROOT_WORKSPACE_ALIAS)

Files to create

Just a manifests.ts (can be in an existing manifests file or a new workspace/ directory):

import { UMB_{ENTITY}_ROOT_ENTITY_TYPE } from '../../entity.js';
import { UMB_{ENTITY}_ROOT_WORKSPACE_ALIAS } from './constants.js';
import { UMB_WORKSPACE_CONDITION_ALIAS } from '@umbraco-cms/backoffice/workspace';

export const manifests: Array<UmbExtensionManifest> = [
	{
		type: 'workspace',
		kind: 'default',
		alias: UMB_{ENTITY}_ROOT_WORKSPACE_ALIAS,
		name: '{EntityName} Root Workspace',
		meta: {
			entityType: UMB_{ENTITY}_ROOT_ENTITY_TYPE,
			headline: '#treeHeaders_{entityPlural}',
		},
	},
	// Optional: add a collection view to list child entities
	{
		type: 'workspaceView',
		kind: 'collection',
		alias: 'Umb.WorkspaceView.{EntityName}Root.Collection',
		name: '{EntityName} Root Collection Workspace View',
		meta: {
			label: 'Collection',
			pathname: 'collection',
			: ,
			: {}_COLLECTION_ALIAS,
		},
		: [
			{
				: ,
				: {}_ROOT_WORKSPACE_ALIAS,
			},
		],
	},
];

Default workspace checklist

• Workspace alias constant defined
• Entity type constant defined
• Manifest has kind: 'default', meta.entityType, and meta.headline
• Workspace views use UMB_WORKSPACE_CONDITION_ALIAS condition
• Manifests wired into parent module's manifests.ts

---

Option B: Routable Workspace (Entity Detail)

For entity detail editing with create/edit URL routing, validation, save flow, and data management.

Prerequisites

Before creating a routable workspace, the entity must already have:

• Entity type constants in entity.ts (constant + root entity type + workspace alias)
• Detail model type (e.g., UmbWebhookDetailModel) in types.ts
• Detail repository + data source + store (see Data Flow)
• Repository manifest registered

Verify these exist before proceeding. If the package doesn't exist yet, use the general-create-package skill first.

Files to create

{package-path}/workspace/
├── constants.ts                              # Re-export context token
├── {entity}-workspace.context-token.ts       # Typed context token
├── {entity}-workspace.context.ts             # Workspace context class
├── {entity}-workspace-editor.element.ts      # Editor shell element
├── manifests.ts                              # workspace + workspaceView + workspaceAction
└── views/
    └── {entity}-details-workspace-view.element.ts  # Main detail view

Step 1: Create context token

File: {entity}-workspace.context-token.ts

import type { Umb{EntityName}WorkspaceContext } from './{entity}-workspace.context.js';
import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
import type { UmbSubmittableWorkspaceContext } from '@umbraco-cms/backoffice/workspace';

export const UMB_{ENTITY}_WORKSPACE_CONTEXT = new UmbContextToken<
	UmbSubmittableWorkspaceContext,
	Umb{EntityName}WorkspaceContext
>(
	'UmbWorkspaceContext',
	undefined,
	(context): context is Umb{EntityName}WorkspaceContext => context.getEntityType?.() === '{entity-type}',
);

Step 2: Create constants.ts

File: constants.ts

export { UMB_{ENTITY}_WORKSPACE_CONTEXT } from './{entity}-workspace.context-token.js';

Step 3: Create workspace context

File: {entity}-workspace.context.ts

Variant A: Simple (no parent hierarchy, like webhook)

import type { Umb{EntityName}DetailRepository } from '../repository/index.js';
import { UMB_{ENTITY}_DETAIL_REPOSITORY_ALIAS } from '../repository/index.js';
import { UMB_{ENTITY}_ENTITY_TYPE, UMB_{ENTITY}_ROOT_ENTITY_TYPE, UMB_{ENTITY}_WORKSPACE_ALIAS } from '../../entity.js';
import type { Umb{EntityName}DetailModel } from '../types.js';
import { Umb{EntityName}WorkspaceEditorElement } from './{entity}-workspace-editor.element.js';
import {
	UmbEntityNamedDetailWorkspaceContextBase,
	UmbWorkspaceIsNewRedirectController,
	UmbWorkspaceIsNewRedirectControllerAlias,
} from '@umbraco-cms/backoffice/workspace';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { UmbSubmittableWorkspaceContext,  }  ;

  {}
	 <{}, {}>
	 , 
{
	
	

	() {
		(host, {
			: {}_WORKSPACE_ALIAS,
			: {}_ENTITY_TYPE,
			: {}_DETAIL_REPOSITORY_ALIAS,
		});

		..([
			{
				: ,
				: {},
				:  () => {
					 .({ : { : {}_ROOT_ENTITY_TYPE, :  } });

					 (
						,
						,
						.().!.()!,
					);
				},
			},
			{
				: ,
				: {},
				:  {
					.();
					.(info...);
				},
			},
		]);
	}

	
	
	
	
	
	
	
}

 { {}  api };

Variant B: Parent-aware (tree entities, like data-type)

Replace the create route with:

{
	path: 'create/parent/:entityType/:parentUnique',
	component: Umb{EntityName}WorkspaceEditorElement,
	setup: async (_component, info) => {
		const parentEntityType = info.match.params.entityType;
		const parentUnique = info.match.params.parentUnique === 'null' ? null : info.match.params.parentUnique;
		await this.createScaffold({ parent: { entityType: parentEntityType, unique: parentUnique } });

		new UmbWorkspaceIsNewRedirectController(
			this,
			this,
			this.getHostElement().shadowRoot!.querySelector('umb-router-slot')!,
		);
	},
},

Step 4: Create editor element

File: {entity}-workspace-editor.element.ts

Uses <umb-workspace-header-name-editable> — a built-in element that auto-consumes the workspace context for name binding, validation, write guard permissions, and auto-focus. No manual name wiring needed.

import { css, html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

// Back path: find or create a constant like UMB_{ENTITY}_SECTION_PATH in the entity's section-path constants.
// Grep for 'SECTION_PATH' or 'WORKSPACE_PATH' in the entity's package to find the correct import.
const BACK_PATH = 'FIXME: replace with section path constant';

@customElement('umb-{entity}-workspace-editor')
export class Umb{EntityName}WorkspaceEditorElement extends UmbLitElement {
	override render() {
		return html`
			<umb-entity-detail-workspace-editor back-path=${BACK_PATH}>
				<umb-workspace-header-name-editable slot="header"></umb-workspace-header-name-editable>
			</umb-entity-detail-workspace-editor>
		`;
	}

	static override styles = [
		css`
			:host {
				display: block;
				width: 100%;
				height: 100%;
			}
		`,
	];
}

 { {}  element };

  {
	  {
		: {};
	}
}

Step 5: Create detail view element

File: views/{entity}-details-workspace-view.element.ts

import { UMB_{ENTITY}_WORKSPACE_CONTEXT } from '../{entity}-workspace.context-token.js';
import type { Umb{EntityName}DetailModel } from '../../types.js';
import { css, customElement, html, state, nothing } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbTextStyles } from '@umbraco-cms/backoffice/style';
import type { UmbWorkspaceViewElement } from '@umbraco-cms/backoffice/workspace';

@customElement('umb-{entity}-details-workspace-view')
export class Umb{EntityName}DetailsWorkspaceViewElement extends UmbLitElement implements UmbWorkspaceViewElement {
	@state()
	private _data?: Umb{EntityName}DetailModel;

	#workspaceContext?: typeof UMB_{ENTITY}_WORKSPACE_CONTEXT.;

	() {
		();

		.({}_WORKSPACE_CONTEXT,  {
			.#workspaceContext = context;
			.(.#workspaceContext?.,  {
				. = data;
			});
		});
	}

	 () {
		 (!.)  nothing;

		 html`;
	}

	  styles = [
		,
		css`,
	];
}

 { {}  element };

  {
	  {
		: {};
	}
}

Step 6: Create manifests

File: manifests.ts

import { UMB_{ENTITY}_ENTITY_TYPE, UMB_{ENTITY}_WORKSPACE_ALIAS } from '../../entity.js';
import { UMB_WORKSPACE_CONDITION_ALIAS, UmbSubmitWorkspaceAction } from '@umbraco-cms/backoffice/workspace';

export const manifests: Array<UmbExtensionManifest> = [
	{
		type: 'workspace',
		kind: 'routable',
		alias: UMB_{ENTITY}_WORKSPACE_ALIAS,
		name: '{EntityName} Workspace',
		api: () => import('./{entity}-workspace.context.js'),
		meta: {
			entityType: UMB_{ENTITY}_ENTITY_TYPE,
		},
	},
	{
		type: 'workspaceView',
		alias: 'Umb.WorkspaceView.{EntityName}.Details',
		name: '{EntityName} Workspace Details View',
		element: () => import('./views/{entity}-details-workspace-view.element.js'),
		weight: 90,
		meta: {
			label: '#general_details',
			: ,
			: ,
		},
		: [
			{
				: ,
				: {}_WORKSPACE_ALIAS,
			},
		],
	},
	{
		: ,
		: ,
		: ,
		: ,
		: ,
		: {
			: ,
			: ,
			: ,
		},
		: [
			{
				: ,
				: {}_WORKSPACE_ALIAS,
			},
		],
	},
];

Step 7: Wire manifests into parent module

Import and spread the workspace manifests in the parent module's manifests.ts:

import { manifests as workspaceManifests } from './workspace/manifests.js';

export const manifests: Array<UmbExtensionManifest> = [
	...workspaceManifests,
	// ... other manifests
];

Routable workspace checklist

• Context token file with correct discriminator (getEntityType() check)
• constants.ts re-exports context token
• Workspace context extends UmbEntityNamedDetailWorkspaceContextBase
• Workspace context exported as api (last line)
• Routes set up with create and edit/:unique paths
• UmbWorkspaceIsNewRedirectController used in create route
• Editor element uses <umb-entity-detail-workspace-editor> with <umb-workspace-header-name-editable slot="header">
• Editor element exports as element and declared on HTMLElementTagNameMap
• View element implements UmbWorkspaceViewElement
• View element exports as element and declared on HTMLElementTagNameMap
• Manifests include workspace, workspaceView, and workspaceAction
• All view/action manifests use UMB_WORKSPACE_CONDITION_ALIAS condition
• Workspace manifests wired into parent module's manifests.ts
• Back path constant set correctly in editor element