# first-run

> Check if it's the first time the process is run

Latest version **4.0.0** (published 2025-09-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install first-run
pnpm add first-run
yarn add first-run
bun add first-run
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.0 |
| Published | 2025-09-12 |
| First published | 2015-07-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 83 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | first, init, initial, run, time, process, start |

## Links

- npm: https://www.npmjs.com/package/first-run
- Repository: https://github.com/sindresorhus/first-run
- Homepage: https://github.com/sindresorhus/first-run#readme
- Issues: https://github.com/sindresorhus/first-run/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/first-run

## Dependencies (1)

- [configstore](https://npm.io/package/configstore.md) ^7.0.0

## Alternatives

- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads

## Recent versions

- 4.0.0 (latest) — 2025-09-12
- 3.0.0 — 2021-10-14
- 2.0.0 — 2019-04-15
- 1.2.0 — 2016-04-06
- 1.1.0 — 2015-09-08
- 1.0.0 — 2015-07-13

## README

# first-run

> Check if it's the first time the process is run

Can be used to greet the user the first time they use your CLI app, show usage tip, initialize something, etc.

## Install

```sh
npm install first-run
```

## Usage

```js
// x.js
import isFirstRun from 'first-run';

console.log(isFirstRun({name: 'x'}));
```

```
$ node x.js
true
$ node x.js
false
```

## API

### isFirstRun(options)

### clearFirstRun(options)

Clear the state.

### isFirstRunForVersion(options)

Check if it's the first time the process is run for this specific version.

Each version is tracked independently from the main `isFirstRun()` function and from other versions.

### clearFirstRunForVersion(options)

Clear the state for a specific version.

#### Example

```js
import {isFirstRunForVersion, clearFirstRunForVersion} from 'first-run';

console.log(isFirstRunForVersion({name: 'my-app', version: '2.1.0'}));
//=> true

console.log(isFirstRunForVersion({name: 'my-app', version: '2.1.0'}));
//=> false

// Clear the state for version 2.1.0
clearFirstRunForVersion({name: 'my-app', version: '2.1.0'});

console.log(isFirstRunForVersion({name: 'my-app', version: '2.1.0'}));
//=> true (cleared!)

console.log(isFirstRunForVersion({name: 'my-app', version: '2.2.0'}));
//=> true (new version!)
```

This is useful for:
- Showing version-specific onboarding or upgrade messages
- Running migration code for new versions
- Tracking feature rollouts per version
- Testing version-specific initialization logic

#### options

Type: `object`

##### name

Type: `string`\
**Required**

The name used to identify it.

Usually, you would fetch the `name` field from package.json.

##### version

Type: `string`\
**(Only for `isFirstRunForVersion` and `clearFirstRunForVersion`)**

The version to track separately. Each version will be tracked independently.

---
_Source: https://npm.io/package/first-run · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._