1# update-notifier [](https://travis-ci.org/yeoman/update-notifier) 2 3> Update notifications for your CLI app 4 5 6 7Inform users of your package of updates in a non-intrusive way. 8 9#### Contents 10 11- [Install](#install) 12- [Usage](#usage) 13- [How](#how) 14- [API](#api) 15- [About](#about) 16- [Users](#users) 17 18 19## Install 20 21``` 22$ npm install update-notifier 23``` 24 25 26## Usage 27 28### Simple 29 30```js 31const updateNotifier = require('update-notifier'); 32const pkg = require('./package.json'); 33 34updateNotifier({pkg}).notify(); 35``` 36 37### Comprehensive 38 39```js 40const updateNotifier = require('update-notifier'); 41const pkg = require('./package.json'); 42 43// Checks for available update and returns an instance 44const notifier = updateNotifier({pkg}); 45 46// Notify using the built-in convenience method 47notifier.notify(); 48 49// `notifier.update` contains some useful info about the update 50console.log(notifier.update); 51/* 52{ 53 latest: '1.0.1', 54 current: '1.0.0', 55 type: 'patch', // Possible values: latest, major, minor, patch, prerelease, build 56 name: 'pageres' 57} 58*/ 59``` 60 61### Options and custom message 62 63```js 64const notifier = updateNotifier({ 65 pkg, 66 updateCheckInterval: 1000 * 60 * 60 * 24 * 7 // 1 week 67}); 68 69if (notifier.update) { 70 console.log(`Update available: ${notifier.update.latest}`); 71} 72``` 73 74 75## How 76 77Whenever you initiate the update notifier and it's not within the interval threshold, it will asynchronously check with npm in the background for available updates, then persist the result. The next time the notifier is initiated, the result will be loaded into the `.update` property. This prevents any impact on your package startup performance. 78The update check is done in a unref'ed [child process](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options). This means that if you call `process.exit`, the check will still be performed in its own process. 79 80The first time the user runs your app, it will check for an update, and even if an update is available, it will wait the specified `updateCheckInterval` before notifying the user. This is done to not be annoying to the user, but might surprise you as an implementer if you're testing whether it works. Check out [`example.js`](example.js) to quickly test out `update-notifier` and see how you can test that it works in your app. 81 82 83## API 84 85### notifier = updateNotifier(options) 86 87Checks if there is an available update. Accepts options defined below. Returns an instance with an `.update` property there is an available update, otherwise `undefined`. 88 89### options 90 91#### pkg 92 93Type: `Object` 94 95##### name 96 97*Required*<br> 98Type: `string` 99 100##### version 101 102*Required*<br> 103Type: `string` 104 105#### updateCheckInterval 106 107Type: `number`<br> 108Default: `1000 * 60 * 60 * 24` *(1 day)* 109 110How often to check for updates. 111 112#### callback(error, update) 113 114Type: `Function` 115 116Passing a callback here will make it check for an update directly and report right away. Not recommended as you won't get the benefits explained in [`How`](#how). `update` is equal to `notifier.update`. 117 118### notifier.notify([options]) 119 120Convenience method to display a notification message. *(See screenshot)* 121 122Only notifies if there is an update and the process is [TTY](https://nodejs.org/api/process.html#process_tty_terminals_and_process_stdout). 123 124#### options 125 126Type: `Object` 127 128##### defer 129 130Type: `boolean`<br> 131Default: `true` 132 133Defer showing the notification to after the process has exited. 134 135##### message 136 137Type: `string`<br> 138Default: [See above screenshot](https://github.com/yeoman/update-notifier#update-notifier-) 139 140Message that will be shown when an update is available. 141 142##### isGlobal 143 144Type: `boolean`<br> 145Default: `true` 146 147Include the `-g` argument in the default message's `npm i` recommendation. You may want to change this if your CLI package can be installed as a dependency of another project, and don't want to recommend a global installation. This option is ignored if you supply your own `message` (see above). 148 149##### boxenOpts 150 151Type: `Object`<br> 152Default: `{padding: 1, margin: 1, align: 'center', borderColor: 'yellow', borderStyle: 'round'}` *(See screenshot)* 153 154Options object that will be passed to [`boxen`](https://github.com/sindresorhus/boxen). 155 156##### shouldNotifyInNpmScript 157 158Type: `boolean`<br> 159Default: `false` 160 161Allows notification to be shown when running as an npm script. 162 163### User settings 164 165Users of your module have the ability to opt-out of the update notifier by changing the `optOut` property to `true` in `~/.config/configstore/update-notifier-[your-module-name].json`. The path is available in `notifier.config.path`. 166 167Users can also opt-out by [setting the environment variable](https://github.com/sindresorhus/guides/blob/master/set-environment-variables.md) `NO_UPDATE_NOTIFIER` with any value or by using the `--no-update-notifier` flag on a per run basis. 168 169The check is also skipped on CI automatically. 170 171 172## About 173 174The idea for this module came from the desire to apply the browser update strategy to CLI tools, where everyone is always on the latest version. We first tried automatic updating, which we discovered wasn't popular. This is the second iteration of that idea, but limited to just update notifications. 175 176 177## Users 178 179There are a bunch projects using it: 180 181- [npm](https://github.com/npm/npm) - Package manager for JavaScript 182- [Yeoman](http://yeoman.io) - Modern workflows for modern webapps 183- [AVA](https://ava.li) - Simple concurrent test runner 184- [XO](https://github.com/xojs/xo) - JavaScript happiness style linter 185- [Pageres](https://github.com/sindresorhus/pageres) - Capture website screenshots 186- [Node GH](http://nodegh.io) - GitHub command line tool 187 188[And 1600+ more…](https://www.npmjs.org/browse/depended/update-notifier) 189 190 191## License 192 193BSD-2-Clause © Google 194
){kind=link}
