Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/favware/npm-deprecate

Programmatically deprecate your NPM published packages matching specified criteria
https://github.com/favware/npm-deprecate

cleanup cli hacktoberfest npm packaging utility

Last synced: about 1 month ago
JSON representation

Programmatically deprecate your NPM published packages matching specified criteria

Host: GitHub
URL: https://github.com/favware/npm-deprecate
Owner: favware
License: mit
Created: 2021-08-23T23:37:51.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2024-05-19T05:30:56.000Z (8 months ago)
Last Synced: 2024-05-19T06:28:14.106Z (8 months ago)
Topics: cleanup, cli, hacktoberfest, npm, packaging, utility
Language: TypeScript
Homepage:
Size: 11 MB
Stars: 10
Watchers: 3
Forks: 0
Open Issues: 2
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md

Awesome Lists containing this project

README

# npm-deprecate

**Programmatically deprecate your NPM published packages**

[![GitHub](https://img.shields.io/github/license/favware/npm-deprecate)](https://github.com/favware/npm-deprecate/blob/main/LICENSE)
[![npm](https://img.shields.io/npm/v/@favware/npm-deprecate?color=crimson&logo=npm)](https://www.npmjs.com/package/@favware/npm-deprecate)

[![Support Server](https://discord.com/api/guilds/512303595966824458/embed.png?style=banner2)](https://join.favware.tech)

## Description

When working on larger libraries it may be desirable to release every commit to
NPM automatically using a GitHub workflow. However when doing this you'll end up
with a LOT of versions on npm, which gets extremely cluttered.

To solve this, one can use this package to programmatically deprecate many
versions at once, matching a glob that is checked against the version name.

## Installation

You can use the following command to install this package, or replace
`npm install -D` with your package manager of choice.

```sh
npm install -D @favware/npm-deprecate
```

Or install it globally:

```sh
npm install -g @favware/npm-deprecate
```

Then call the script with `npm-deprecate` or `nd`:

```sh
npm-deprecate --name "*next*" --package "@favware/npm-deprecate" # Add any other flags or use --help
nd --name "*next*" --package "@favware/npm-deprecate" # Add any other flags or use --help
```

Alternatively you can call the CLI directly with `npx`:

```sh
npx @favware/npm-deprecate --name "*next*" --package "@favware/npm-deprecate" # Add any other flags or use --help
```

## Usage

### Environment Variables

The following environment variables have to be set before running this script:

| Name | Required | Description |
| ----------------- | -------- | --------------------------------------------------------------- |
| `NODE_AUTH_TOKEN` | Yes | The NPM Automation Token that can be used to deprecate versions |

### Configuration

You can provide all options through CLI flags:

```sh
Usage: npm-deprecate [options]

Options:
-V, --version output the version number
-n, --name A glob pattern that will determine which packages are deprecated. Anything that passes
[Micromatch](https://www.npmjs.com/package/micromatch) will work here. For example set `*dev*` to match `13.2.0-dev.123a`.
-d, --deprecate-dist-tag [deprecateDistTag] Whether the version that is in the current dist tags should be preserved or not. By default dist tags are preserved. When set
to `true`, dist tags are pruned. (default: false)
-m, --message [message] A custom message to show for all the deprecated versions. (default: "This version has been automatically deprecated by
@favware/npm-deprecate. Please use a newer version.")
-v, --verbose Print verbose information (default: false)
-p, --package Repeatable, each will be treated as another package. The packages that should be deprecated
-h, --help display help for command
```

Or, you can set most of these options through a configuration file. This file
should be located at your current working directory (where you're calling this
package). It should be named `.npm-deprecaterc`, optionally suffixed with
`.json`, `.yaml`, or `.yml`.

### Config file fields

- `--name` maps to `name`
- `--deprecate-dist-tag` maps to `deprecateDistTag`
- `--verbose` maps to `verbose`
- `--message` maps to `message`
- `--package` maps to `package`

When using `.npm-deprecaterc` or `.npm-deprecaterc.json` as your config file you
can also use the JSON schema to get schema validation. To do so, add the
following to your config file:

```json
{
"$schema": "https://raw.githubusercontent.com/favware/npm-deprecate/main/assets/npm-deprecate.schema.json"
}
```

**Example JSON file**:

```json
{
"$schema": "https://raw.githubusercontent.com/favware/npm-deprecate/main/assets/npm-deprecate.schema.json",
"name": "*next*",
"deprecateDistTag": false,
"verbose": true,
"package": ["@favware/cliff-jumper", "@favware/npm-deprecate"]
}
```

**Example YAML file**:

```yaml
name: '*next*'
deprecateDistTag: false
verbose: true
package:
- '@favware/cliff-jumper'
- '@favware/npm-deprecate'
```

### Default values

This library has opinionated defaults for its options. These are as follows:

- `--deprecate-dist-tag` will default to `false`.
- `--message` will default to
`This version has been automatically deprecated by @favware/npm-deprecate. Please use a newer version.`.
- `--verbose` will default to `false`.

### Using this in a GitHub Workflow

```yaml
name: NPM Auto Deprecate

on:
schedule:
- cron: '0 0 * * *'

jobs:
auto-deprecate:
name: NPM Auto Deprecate
runs-on: ubuntu-latest
steps:
- name: Checkout Project
uses: actions/checkout@v2
- name: Use Node.js v18
uses: actions/setup-node@v2
with:
node-version: 18
cache: yarn
registry-url: https://registry.npmjs.org/
- name: Install Dependencies if Cache Miss
run: yarn --immutable
- name: Deprecate versions
run: yarn npm-deprecate
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_PUBLISH_TOKEN }}
```

## Buy us some doughnuts

Favware projects are and always will be open source, even if we don't get
donations. That being said, we know there are amazing people who may still want
to donate just to show their appreciation. Thank you very much in advance!

We accept donations through Ko-fi, Paypal, Patreon, GitHub Sponsorships, and
various cryptocurrencies. You can use the buttons below to donate through your
method of choice.

## Contributors

Please make sure to read the [Contributing Guide][contributing] before making a
pull request.

Thank you to all the people who already contributed!

[contributing]: .github/CONTRIBUTING.md