1 | # @oclif/plugin-warn-if-update-available
|
2 |
|
3 | warns if there is a newer version of CLI released
|
4 |
|
5 | [![Version](https://img.shields.io/npm/v/@oclif/plugin-warn-if-update-available.svg)](https://npmjs.org/package/@oclif/plugin-warn-if-update-available)
|
6 | [![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)
|
7 | [![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)
|
8 |
|
9 |
|
10 | * [@oclif/plugin-warn-if-update-available](#oclifplugin-warn-if-update-available)
|
11 | * [What is this?](#what-is-this)
|
12 | * [How it works](#how-it-works)
|
13 | * [Installation](#installation)
|
14 | * [Configuration](#configuration)
|
15 | * [Environment Variables](#environment-variables)
|
16 | * [Contributing](#contributing)
|
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 once every 60 days by default (see [Configuration](#configuration) for how to configure this). 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 | - `frequency` - The frequency that the new version warning should be shown.
|
54 | - `frequencyUnit` - The unit of time that should be used to calculate the frequency (`days`, `hours`, `minutes`, `seconds`, `milliseconds`). Defaults to `minutes`.
|
55 |
|
56 | ## Example configuration
|
57 |
|
58 | ```json
|
59 | {
|
60 | "oclif": {
|
61 | "plugins": ["@oclif/plugin-warn-if-update-available"],
|
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 | ```
|
71 |
|
72 | ## Notification Frequency
|
73 |
|
74 | Once a new version has been found, the default behavior is to notify the user on every command execution. You can modify this by setting the `frequency` and `frequencyUnit` options.
|
75 |
|
76 | **Examples**
|
77 |
|
78 | Once every 10 minutes.
|
79 |
|
80 | ```json
|
81 | {
|
82 | "oclif": {
|
83 | "warn-if-update-available": {
|
84 | "frequency": 10
|
85 | }
|
86 | }
|
87 | }
|
88 | ```
|
89 |
|
90 | Once every 6 hours.
|
91 |
|
92 | ```json
|
93 | {
|
94 | "oclif": {
|
95 | "warn-if-update-available": {
|
96 | "frequency": 6,
|
97 | "frequencyUnit": "hours"
|
98 | }
|
99 | }
|
100 | }
|
101 | ```
|
102 |
|
103 | Once a day.
|
104 |
|
105 | ```json
|
106 | {
|
107 | "oclif": {
|
108 | "warn-if-update-available": {
|
109 | "frequency": 1,
|
110 | "frequencyUnit": "days"
|
111 | }
|
112 | }
|
113 | }
|
114 | ```
|
115 |
|
116 | Once every 30 seconds.
|
117 |
|
118 | ```json
|
119 | {
|
120 | "oclif": {
|
121 | "warn-if-update-available": {
|
122 | "frequency": 30,
|
123 | "frequencyUnit": "seconds"
|
124 | }
|
125 | }
|
126 | }
|
127 | ```
|
128 |
|
129 | # Environment Variables
|
130 |
|
131 | - `<CLI>_SKIP_NEW_VERSION_CHECK`: Skip this version check
|
132 | - `<CLI>_FORCE_VERSION_CACHE_UPDATE`: Force the version cache to update
|
133 | - `<CLI>_NEW_VERSION_CHECK_FREQ`: environment variable override for `frequency` setting
|
134 | - `<CLI>_NEW_VERSION_CHECK_FREQ_UNIT`: environment variable override for `frequencyUnit` setting
|
135 |
|
136 | # Contributing
|
137 |
|
138 | See [contributing guide](./CONRTIBUTING.md)
|