^{Originally posted by madcampos April 22, 2026}

Motivation

When changes happen in a project, we may want to mark it as deprecated to alert other developers to avoid using something, and optionally point them to use something else instead.

Proposal

Add a new @deprecated decorator.
The value for this decorator is the message to display about this variable.

E.g.:

# Some old variable
# @deprecated
SOME_OLD_VARIABLE=

# Some old variable, with message
# @deprecated="Use NEW_VARIABLE instead"
ANOTHER_OLD_VARIABLE=

NEW_VARIABLE=

That in turn would add the @deprecated JSDoc annotation to generated types, like so:

export type CoercedEnvSchema = {
  /**
   * **SOME_OLD_VARIABLE** 
   * Some old variable  
   * @deprecated
   */
  SOME_OLD_VARIABLE: string;

  /**
   * **ANOTHER_OLD_VARIABLE** 
   * Some old variable, with message  
   * @deprecated Use NEW_VARIABLE instead
   */
  ANOTHER_OLD_VARIABLE: string;
  
  //...
}
```</div>