0
# Update Browserslist DB
1

2
Update Browserslist DB is a CLI tool that updates the `caniuse-lite` database to refresh target browsers from Browserslist configuration. It automatically detects package managers (npm, yarn, pnpm, bun) and updates the caniuse-lite dependency to ensure browser queries use the most current browser data, reducing unnecessary polyfills and improving website performance.
3

4
## Package Information
5

6
- **Package Name**: update-browserslist-db
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install update-browserslist-db` or `npx update-browserslist-db@latest`
10

11
## Core Imports
12

13
```javascript
14
const updateDb = require("update-browserslist-db");
15
```
16

17
For TypeScript:
18

19
```typescript
20
import updateDb = require("update-browserslist-db");
21
// or with type annotations
22
const updateDb: (print?: (str: string) => void) => void = require("update-browserslist-db");
23
```
24

25
## Basic Usage
26

27
### CLI Usage
28

29
```bash
30
# Update caniuse-lite database
31
npx update-browserslist-db@latest
32

33
# Show help
34
npx update-browserslist-db --help
35
npx update-browserslist-db -h
36

37
# Show version
38
npx update-browserslist-db --version
39
npx update-browserslist-db -v
40
```
41

42
### Programmatic Usage
43

44
```javascript
45
const updateDb = require("update-browserslist-db");
46

47
// Use default stdout output
48
updateDb();
49

50
// Custom output handling
51
updateDb((message) => {
52
  console.log("Custom:", message);
53
});
54
```
55

56
## Architecture
57

58
The package consists of several key components:
59

60
- **Main Function**: `updateDb()` orchestrates the entire update process
61
- **Package Manager Detection**: Automatically detects npm, yarn, pnpm, or bun lockfiles
62
- **Version Management**: Fetches latest caniuse-lite version and compares with installed versions
63
- **Lockfile Updates**: Updates package manager lockfiles with new caniuse-lite version
64
- **Browser Analysis**: Shows target browser changes when browserslist is available
65
- **Error Handling**: Custom error types for different failure scenarios
66

67
## Capabilities
68

69
### Database Update
70

71
Updates the caniuse-lite database to the latest version, ensuring up-to-date browser data for tools like Autoprefixer and Babel.
72

73
```javascript { .api }
74
/**
75
 * Run update and print output to terminal.
76
 * @param {function} [print] - Optional function to handle output strings
77
 */
78
function updateDb(print?: (str: string) => void): void
79
```
80

81
The function:
82
- Detects the package manager being used (npm, yarn, pnpm, bun)
83
- Fetches the latest caniuse-lite version information
84
- Updates the lockfile to use the latest version
85
- Shows browser target changes if browserslist is available
86
- Handles errors gracefully with custom error types
87

88
**Usage Examples:**
89

90
```javascript
91
const updateDb = require("update-browserslist-db");
92

93
// Basic usage with default output
94
updateDb();
95

96
// Custom output handling for logging
97
updateDb((message) => {
98
  // Strip ANSI color codes if needed
99
  const cleanMessage = message.replace(/\x1b\[\d+m/g, '');
100
  logger.info('Browserslist update:', cleanMessage);
101
});
102

103
// Capture output for processing
104
let outputBuffer = '';
105
updateDb((message) => {
106
  outputBuffer += message;
107
});
108
```
109

110
### Error Handling
111

112
Custom error class for browserslist update-specific errors. This error is thrown by the `updateDb()` function when update-specific issues occur.
113

114
```javascript { .api }
115
/**
116
 * Custom error class for browserslist update-specific errors
117
 * @param {string} message - Error message
118
 */
119
function BrowserslistUpdateError(message: string): BrowserslistUpdateError
120

121
// Error instance properties:
122
interface BrowserslistUpdateErrorInstance extends Error {
123
  name: "BrowserslistUpdateError";
124
  message: string;          // Descriptive error message
125
  browserslist: true;       // Marker property to identify browserslist errors
126
}
127
```
128

129
Common error scenarios:
130
- Missing package.json file
131
- No lockfile found (missing npm/yarn/pnpm installation)
132
- Package manager command execution failures
133
- Browserslist configuration errors
134

135
**Usage Example:**
136

137
```javascript
138
const updateDb = require("update-browserslist-db");
139

140
try {
141
  updateDb();
142
} catch (error) {
143
  if (error.name === 'BrowserslistUpdateError') {
144
    console.error('Browserslist update failed:', error.message);
145
    // Handle browserslist-specific errors
146
  } else {
147
    throw error; // Re-throw other errors
148
  }
149
}
150
```
151

152

153
## Supported Package Managers
154

155
The tool automatically detects and supports:
156

157
- **npm**: via `package-lock.json` or `npm-shrinkwrap.json`
158
- **yarn v1**: via `yarn.lock` (manual lockfile update)
159
- **yarn v2+**: via `yarn.lock` (uses `yarn up -R caniuse-lite`)
160
- **pnpm**: via `pnpm-lock.yaml` (uses `pnpm up caniuse-lite`)
161
- **bun**: via `bun.lock` or `bun.lockb` (uses `bun update caniuse-lite`)
162

163
## Error Scenarios
164

165
The tool handles several error conditions gracefully:
166

167
1. **Missing package.json**: "Cannot find package.json. Is this the right directory to run `npx update-browserslist-db` in?"
168
2. **Missing lockfile**: "No lockfile found. Run 'npm install', 'yarn install' or 'pnpm install'"
169
3. **Missing browserslist**: Shows gray message about installing browserslist for target browser changes
170
4. **Package manager errors**: Shows command output and suggests manual execution
171
5. **Browser list retrieval errors**: Shows warning that target browser changes won't be shown
172

173
## Internal Data Structures
174

175
The following data structures are used internally by the package:
176

177
```javascript { .api }
178
// Output handler function type
179
// function(str: string) => void
180

181
// Package manager detection result
182
// {
183
//   file: string,           // Path to lockfile
184
//   mode: string,           // "npm" | "yarn" | "pnpm" | "bun"
185
//   content?: string,       // Lockfile content (when loaded)
186
//   version?: number        // Yarn lockfile version (1 or 2)
187
// }
188

189
// Latest package version information  
190
// {
191
//   version: string,        // Latest version number
192
//   dist: {
193
//     tarball: string,      // Download URL
194
//     integrity?: string    // SRI hash (optional)
195
//   }
196
// }
197

198
// Browser list data structure
199
// {
200
//   [browser: string]: string[]  // Browser name -> array of versions
201
// }
202
```
203

204
## TypeScript Support
205

206
The package includes complete TypeScript definitions:
207

208
```typescript { .api }
209
/**
210
 * Run update and print output to terminal.
211
 */
212
declare function updateDb(print?: (str: string) => void): void
213

214
export = updateDb
215
```