Skip to main content

Deprecating a Package

Sometimes a published package turns out to be the wrong call — a design that conflicts with a philosophy discovered too late, an approach superseded by a better one, or simply something that shouldn't have shipped as-is. This page covers how to wind one down cleanly, in an order that avoids leaving broken links, silently-abandoned code, or confused consumers behind.

Order Matters​

The steps below have a specific, non-obvious ordering constraint: once a repository is archived, nothing can be pushed to it again. Do the history preservation and documentation work first, while the repository is still writable, and archive it last.

1. Preserve History in Its Own Repository​

Don't just delete the package's directory from a monorepo — its commit history (including the investigation that led to deprecating it) has value on its own. Extract it into a standalone repository before removing it from the monorepo:

git subtree split --prefix=path/to/package -b package-history
git push https://github.com/your-account-or-org/package-name-archive.git package-history:main

2. Explain Why, in the Repository Itself​

Before archiving, update the extracted repository's README with a clear, upfront explanation of why it's deprecated — not just that it is. Future readers (including your own future self) benefit far more from the reasoning than from a bare "deprecated" label:

> ⚠️ **This package is deprecated and archived.**
>
> [Explain the specific reasoning — e.g., a design conflict discovered
> after publishing, or a better pattern that supersedes this one — and
> link to whatever documents the corrected approach.]
>
> This repository is kept for historical/reference purposes only and
> receives no further updates.

If the deprecation reverses an earlier public position (a README that once defended keeping the package, a comment thread where you argued for it), say so directly rather than letting the two statements sit in public contradiction of each other. Being visibly wrong once and correcting it in the open costs less credibility than an unexplained flip.

3. Deprecate on the Package Registry​

npm deprecate your-package-name "This package is deprecated: [brief reason]. See [link to archived repo / replacement guidance] for details."

This surfaces a warning to anyone who still installs it, without removing it outright — existing consumers aren't broken by a sudden 404.

4. Remove It From the Active Monorepo​

Only after the history is safely preserved elsewhere and the deprecation notice is live:

git rm -r path/to/package
git commit -m "Remove <package>: deprecated, moved to <archive-repo-url>"
git push

5. Update Everything That Referenced It​

This is easy to miss, and it's the step most likely to leave stale, confusing content behind if skipped:

  • Any documentation page that recommended the deprecated package needs rewriting to point at the corrected approach — not just a note appended saying "this is deprecated," but content that actually reflects the current recommendation. A reader shouldn't have to read a deprecation warning and then go find the real answer somewhere else.
  • Public discussion threads (GitHub issues, forum posts) where you previously recommended the package deserve a follow-up comment correcting the record, with the reasoning and a link to the replacement guidance — the same audience that saw the original recommendation is the audience that needs to see the correction.
  • Any announcement content (blog posts, changelogs) introducing the package should either be updated or left as-is with a prominent addition noting the reversal — don't leave it looking current if it no longer is.

6. Archive the Repository Last​

gh repo archive your-account-or-org/package-name-archive --yes

Only once steps 1-5 are done. Archiving is effectively permanent for practical purposes (unarchiving is possible but not the intended workflow) — treat it as the final, one-way step in the sequence, not something to do early "to be safe."

Why Bother With All of This, Instead of Just Deleting It​

A silently-deleted package leaves broken installs, dead links in anyone else's writing that referenced it, and no explanation for why it's gone. The steps above cost some extra time, but they turn a mistake into a documented decision — which is a meaningfully different thing to leave behind than an unexplained disappearance.