1 | @oclif/plugin-warn-if-update-available
|
2 | ======================================
|
3 |
|
4 | warns if there is a newer version of CLI released
|
5 |
|
6 | [![Version](https://img.shields.io/npm/v/@oclif/plugin-warn-if-update-available.svg)](https://npmjs.org/package/@oclif/plugin-warn-if-update-available)
|
7 | [![CircleCI](https://circleci.com/gh/oclif/plugin-warn-if-update-available/tree/main.svg?style=shield)](https://circleci.com/gh/oclif/plugin-warn-if-update-available/tree/main)
|
8 | [![Appveyor CI](https://ci.appveyor.com/api/projects/status/github/oclif/plugin-warn-if-update-available?branch=main&svg=true)](https://ci.appveyor.com/project/oclif/plugin-warn-if-update-available/branch/main)
|
9 | [![Downloads/week](https://img.shields.io/npm/dw/@oclif/plugin-warn-if-update-available.svg)](https://npmjs.org/package/@oclif/plugin-warn-if-update-available)
|
10 | [![License](https://img.shields.io/npm/l/@oclif/plugin-warn-if-update-available.svg)](https://github.com/oclif/plugin-warn-if-update-available/blob/main/package.json)
|
11 |
|
12 |
|
13 | * [What is this?](#what-is-this)
|
14 | * [How it works](#how-it-works)
|
15 | * [Installation](#installation)
|
16 | * [Configuration](#configuration)
|
17 |
|
18 |
|
19 | # What is this?
|
20 |
|
21 | This plugin shows a warning message if a user is running an out of date CLI.
|
22 |
|
23 | ![screenshot](./assets/screenshot.png)
|
24 |
|
25 | # How it works
|
26 |
|
27 | This checks the version against the npm registry asynchronously in a forked process, at most once per 7 days. It then saves a version file to the cache directory that will enable the warning. The upside of this method is that it won't block a user while they're using your CLI—the downside is that it will only display _after_ running a command that fetches the new version.
|
28 |
|
29 | # Installation
|
30 |
|
31 | Add the plugin to your project with `yarn add @oclif/plugin-warn-if-update-available`, then add it to the `package.json` of the oclif CLI:
|
32 |
|
33 | ```js
|
34 | {
|
35 | "name": "mycli",
|
36 | "version": "0.0.0",
|
37 | // ...
|
38 | "oclif": {
|
39 | "plugins": ["@oclif/plugin-help", "@oclif/plugin-warn-if-update-available"]
|
40 | }
|
41 | }
|
42 | ```
|
43 |
|
44 | # Configuration
|
45 |
|
46 | In `package.json`, set `oclif['warn-if-update-available']` to an object with
|
47 | any of the following configuration properties:
|
48 |
|
49 | - `timeoutInDays` - Duration between update checks. Defaults to 60.
|
50 | - `message` - Customize update message.
|
51 | - `registry` - URL of registry. Defaults to the public npm registry: `https://registry.npmjs.org`
|
52 | - `authorization` - Authorization header value for registries that require auth.
|
53 |
|
54 | ## Example configuration
|
55 |
|
56 | ```json
|
57 | {
|
58 | "oclif": {
|
59 | "plugins": [
|
60 | "@oclif/plugin-warn-if-update-available"
|
61 | ],
|
62 | "warn-if-update-available": {
|
63 | "timeoutInDays": 7,
|
64 | "message": "<%= config.name %> update available from <%= chalk.greenBright(config.version) %> to <%= chalk.greenBright(latest) %>.",
|
65 | "registry": "https://my.example.com/module/registry",
|
66 | "authorization": "Basic <SOME READ ONLY AUTH TOKEN>"
|
67 | }
|
68 | }
|
69 | }
|
70 | ```
|