OpenParable
Skip to content
← Back to skills

Core Add Module

Development
core-add-module

Core Add Module 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 module to the core package (src/packages/core/). Use when adding shared UI framework infrastructure that all packages can use — e.g., a new extension system feature, a new utility, a new shared component pattern, a new picker, or a new workspace primitive. Core modules are imported as @umbraco-cms/backoffice/{module-name}. Also use when the user says things like "add a module to core", "create a new core feature", or "add shared infrastructure".

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/core-add-module/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/core-add-module, 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 Core Module

Add a new module to the core package (src/packages/core/).

Naming conventions

  • Module names are singular (e.g., picker, sorter, entity-flag, modal, section)

What you need from the user

  1. Module name — What to call it in singular form (kebab-case, e.g., picker, sorter, entity-flag)
  2. Purpose — What shared infrastructure this provides

When to add to core vs. create a new package

  • Core module: Shared UI framework infrastructure used by multiple packages — extension primitives, pickers, validation, repository base classes, workspace utilities.
  • New package: Domain-specific CMS features (documents, media, webhook). Use the create-package skill instead.

Core modules should not implement CMS-specific features. They provide the building blocks that CMS feature packages use.

Files to create

src/packages/core/{module-name}/
├── index.ts                   # Public API exports
├── manifests.ts               # Extension registrations (if any)
├── constants.ts               # Module constants
└── types.ts                   # Module types

Step 1: Create the module directory and files

{module-name}/index.ts

The public API. Only export what other packages need:

export * from './constants.js';
export type * from './types.js';

Use export type * for type-only exports.

{module-name}/manifests.ts

Extension registrations for this module:

export const manifests: Array<UmbExtensionManifest> = [
	// Extension registrations
];

If the module has no extensions (pure utility), export an empty array.

{module-name}/constants.ts

// Aliases, context tokens, entity types

{module-name}/types.ts

// Type definitions, interfaces, meta types

Step 2: Wire into core's manifests.ts

Add the module's manifests to src/packages/core/manifests.ts:

import { manifests as {moduleName}Manifests } from './{module-name}/manifests.js';

// In the manifests array:
...{moduleName}Manifests,

The imports are in alphabetical order — insert in the right position.

Step 3: Add entry point to core's vite.config.ts

Add the module to the entry object in src/packages/core/vite.config.ts:

'{module-name}/index': './{module-name}/index.ts',

The entries are in alphabetical order — insert in the right position. This tells Vite to build the module as a separate entry point.

Step 4: Register the subpath export

Add to the exports field in the root package.json (src/Umbraco.Web.UI.Client/package.json):

"./{module-name}": "./dist-cms/packages/core/{module-name}/index.js"

This enables imports like @umbraco-cms/backoffice/{module-name}.

Step 5: Regenerate TypeScript config

npm run generate:tsconfig

This updates tsconfig.json paths so the new module resolves correctly in TypeScript.

How consumers import

After registration, other packages import from the module like:

import { MyThing } from '@umbraco-cms/backoffice/{module-name}';
import type { MyType } from '@umbraco-cms/backoffice/{module-name}';

Reference: existing core modules to study

  • Simple utility: src/packages/core/culture/ — repository + components, minimal surface
  • Extension primitive: src/packages/core/entity-action/ — kinds, base classes, shared element
  • Infrastructure: src/packages/core/repository/ — base classes for the data access pattern

Checklist

  • Module directory created under src/packages/core/
  • index.ts exports only the public API
  • manifests.ts exports extension registrations (or empty array)
  • constants.ts and types.ts created
  • Module manifests imported in src/packages/core/manifests.ts (alphabetical order)
  • Entry point added to src/packages/core/vite.config.ts (alphabetical order)
  • Subpath export added to root package.json
  • npm run generate:tsconfig executed
  • Compiles: npm run compile