@deprecated marks a declaration that should no longer be used. Since TypeScript 4.0, editors read it: every use of the name is struck through, the hover shows the tag's text, and completion lists mark the entry. It works the same in .js and .ts files.
It is not an error. TypeScript reports a deprecated use as a suggestion diagnostic, the kind editors show but tsc does not print, so the examples on this page pass. To fail a build on deprecated calls, use a linter rule.
At a glance
| Use | JSDoc in a .js file | TypeScript in a .ts file |
|---|---|---|
| A deprecated function | /** @deprecated Use cartTotal(). */
function sumPrices(prices) { … } | /** @deprecated Use cartTotal(). */
function sumPrices(prices: number[]) { … } |
| Pointing to the replacement | /** @deprecated Use {@link cartTotal}. */ | /** @deprecated Use {@link cartTotal}. */ |
Examples
/**
* @deprecated Use {@link cartTotal}, which takes the line items.
* @param {number[]} prices
* @returns {number}
*/
export function sumPrices(prices) {
return prices.reduce((sum, price) => sum + price, 0);
}
/**
* @param {{ price: number, quantity: number }[]} lines
* @returns {number}
*/
export function cartTotal(lines) {
return lines.reduce((sum, line) => sum + line.price * line.quantity, 0);
}
// tsc reports nothing; editors strike the name through and say it is deprecated.
sumPrices([19.5, 12]);jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}export class Cart {
/** @type {{ sku: string, quantity: number }[]} */
lines = [];
/**
* @deprecated Use `lines.length`.
* @type {number}
*/
size = 0;
/**
* @deprecated Use {@link Cart#add}.
* @param {string} sku
*/
addItem(sku) {
this.add(sku, 1);
}
/**
* @param {string} sku
* @param {number} quantity
*/
add(sku, quantity) {
this.lines.push({ sku, quantity });
}
}
const cart = new Cart();
cart.addItem("TEE-01");
cart.size;export class Cart {
lines: { sku: string; quantity: number }[] = [];
/** @deprecated Use `lines.length`. */
size: number = 0;
/** @deprecated Use {@link Cart#add}. */
addItem(sku: string) {
this.add(sku, 1);
}
add(sku: string, quantity: number) {
this.lines.push({ sku, quantity });
}
}
const cart = new Cart();
cart.addItem("TEE-01");
cart.size;jsconfig.json for this example
{
"compilerOptions": {
"checkJs": true,
"noEmit": true,
"strict": true,
"target": "es2022",
"module": "nodenext",
"types": []
},
"include": ["*.js"]
}What editors show
Each use of a deprecated name gets a suggestion diagnostic from TypeScript's language service: TS6385 ("'sumPrices' is deprecated") for variables and properties, TS6387 for a call to a deprecated signature. Editors draw these as a strike-through rather than a squiggle. We confirmed both codes by asking the language service for the suggestions on the examples.
Write the reason and the replacement in the tag's text, ideally with {@link}, so the hover becomes a pointer to the new code: @deprecated Use {@link cartTotal}, which takes the line items.
What can be deprecated
Functions, classes, methods, properties and variables all take the tag. The examples deprecate a function, a method and a class field; the TypeScript tab shows that the comment is the same in a .ts file, where only the types move out of it.
Gotchas
- The tag must be in the declaration's own JSDoc comment, on its own lines above the declaration. A comment on the same line as an opening brace is not attached to the member that follows it.
- A deprecated declaration can still be used freely; nothing in
tsc --noEmitoutput changes. Teams that want a hard stop add a lint rule for deprecated APIs.
Questions
Why does my deprecated function not show an error?
Because TypeScript treats deprecation as a suggestion, not an error. Editors strike the name through; tsc prints nothing for it.
Sources
- TypeScript 4.0: /** @deprecated */ support · TypeScript release notes
- JSDoc Reference: @deprecated · TypeScript handbook
- @deprecated · JSDoc
Last reviewed 20 October 2026.