Deprecate a public API (class, method, property, type, constant, or context token) following the 2-major-version rule. Use when removing or replacing any publicly exported symbol that external consumers may depend on — includes exports from package index.ts files, global components, extension type aliases, and manifest schemas.
Deprecate a public API following Umbraco's breaking changes policy.
version.json at the repository rootDeprecated in vN -> earliest removal in vN+2.
Example: deprecated in v17 -> scheduled for removal in v19.
Read version.json to determine the current major version and calculate the removal version.
Every deprecation must use both:
@deprecated tag — for IDE warnings and documentationUmbDeprecation runtime warning — for console output at runtimeIntroduce the new API alongside the old one. The old API should delegate to the new implementation internally.
// New method (the replacement)
requestSummary() {
// Real implementation here
}
@deprecated tagInclude: what was deprecated, when, the replacement, and when it will be removed.
/**
* @deprecated Deprecated since v17. Use `requestSummary()` instead. Will be removed in v19.
*/
getSummary() {
return this.requestSummary();
}
For types and interfaces:
/**
* @deprecated Deprecated since v17. Use `UmbNewInterface` instead. Scheduled for removal in Umbraco 19.
*/
export interface UmbOldInterface {
// ...
}
UmbDeprecation runtime warningimport { UmbDeprecation } from '@umbraco-cms/backoffice/utils';
/**
* @deprecated Deprecated since v17. Use `requestSummary()` instead. Will be removed in v19.
*/
getSummary() {
new UmbDeprecation({
deprecated: 'UmbMyContext.getSummary()',
removeInVersion: '19.0.0',
solution: 'Use requestSummary() instead.',
}).warn();
return this.requestSummary();
}
| Symbol | Where to place UmbDeprecation |
|---|---|
| Method | Inside the method body |
| Class | In the constructor |
| Property getter | Inside the getter |
| Constant | At module level (executes on import) |
/**
* @deprecated Deprecated since v17. Use `UmbNewRepository` instead. Will be removed in v19.
*/
export class UmbOldRepository extends UmbControllerBase {
constructor(host: UmbControllerHost) {
super(host);
new UmbDeprecation({
deprecated: 'UmbOldRepository is deprecated.',
removeInVersion: '19.0.0',
solution: 'Use UmbNewRepository instead.',
}).warn();
}
}
The deprecated API must keep working. Delegate to the replacement internally:
/**
* @deprecated Deprecated since v17. Use `getContentTypeUnique()` instead. Will be removed in v19.
*/
getContentTypeId(): string | undefined {
new UmbDeprecation({
deprecated: 'UmbMemberWorkspaceContext.getContentTypeId()',
removeInVersion: '19.0.0',
solution: 'Use getContentTypeUnique() instead.',
}).warn();
return this.getContentTypeUnique();
}
All internal code must use the new API. No code within the repository should call the deprecated member.
Any of the following to a publicly exported symbol:
package.jsonNot breaking: Internal code (unexported classes, private methods) can be changed freely without deprecation.
@deprecated JSDoc tag added with: since version, replacement, removal versionUmbDeprecation runtime warning added with deprecated, removeInVersion, solutionnpm run compile