OpenParable
Skip to content
← Back to skills

General Add Value Type

Development
general-add-value-type

General Add Value Type is an Agent Skill for development published in the umbraco/Umbraco-CMS repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Add a new value type — a named, typed string constant that extends UmbValueTypeMap. Use when a feature needs to declare what type of value it holds so it can be referenced in collection columns or value summary manifests. Also use when a property editor needs to expose its value type for use in collection views.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/umbraco/Umbraco-CMS/blob/HEAD/src/Umbraco.Web.UI.Client/.claude/skills/general-add-value-type/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/general-add-value-type, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Add Value Type

Add a new value type constant to UmbValueTypeMap.

Foundational documentation

Read before proceeding:

  • Value Type — full reference, naming convention, rules

What you need from the user

  1. Feature name — kebab-case (e.g., color-picker, user-group)
  2. Package path — where the feature lives (e.g., src/packages/property-editors/color-picker/)
  3. Value type key — the string alias:
    • For a property editor: use the schema alias (e.g., 'Umbraco.ColorPicker')
    • For a domain type: use Umb.ValueType.{Entity}.{Shape} (e.g., 'Umb.ValueType.UserGroup.References')
  4. TypeScript type — the type of the raw value (e.g., string, boolean, UmbReferenceByUnique[])

Step 1: Create the constant file

File: {package-path}/value-type/constants.ts

export const UMB_{FEATURE}_VALUE_TYPE = '{value-type-key}' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_{FEATURE}_VALUE_TYPE]: {TValue};
	}
}

Rules:

  • The string value is always as const.
  • The declare global block is in the same file as the constant.
  • One constant per file — do not group multiple value types.

Property editor example

import type { UmbColorPickerPropertyEditorValue } from '../types.js';

export const UMB_COLOR_PICKER_VALUE_TYPE = 'Umbraco.ColorPicker' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_COLOR_PICKER_VALUE_TYPE]: UmbColorPickerPropertyEditorValue;
	}
}

Domain type example

import type { UmbReferenceByUnique } from '@umbraco-cms/backoffice/models';

export const UMB_USER_GROUP_REFERENCES_VALUE_TYPE = 'Umb.ValueType.UserGroup.References' as const;

declare global {
	interface UmbValueTypeMap {
		[UMB_USER_GROUP_REFERENCES_VALUE_TYPE]: UmbReferenceByUnique[];
	}
}

Step 2: Export from the package index

Add to the package index.ts:

export * from './value-type/constants.js';

Checklist

  • Constant declared with as const
  • declare global block extends UmbValueTypeMap in the same file
  • Key follows naming convention (schema alias for property editors, Umb.ValueType.{Entity}.{Shape} for domain types)
  • TypeScript type is the correct raw value type
  • One constant per file
  • Constant exported from package index.ts
  • Compiles: npm run compile