---
name: bump-deps
description: Update one or more npm dependencies safely (respects .ncurc.json)
---

# Command: `/bump-deps`

Bump one or more dependencies in `package.json`, then verify lint + tests + build still pass.

## When to use

- The user asks to "bump X to version Y"
- The weekly `check_packages_versions.yml` workflow opened a PR that needs review
- A security advisory or feature requires a newer version
- Routine maintenance

## Inputs to confirm

- **Which dependency** — `@twemoji/parser`, `typescript`, `mocha`, etc.
- **Target version** — exact version string, or "latest" / "patch" / "minor"
- **Why** — feature, security, hygiene

## Pre-flight: optional `.ncurc.json` rejects

```json
{
  "upgrade": true,
  "reject": []
}
```

Add package names to `reject` only when an upgrade needs deliberate follow-up (breaking API, ecosystem lag). **`chai` and `eslint` are no longer repo-wide pins** — we ship Chai 6 + ESLint 10 (`eslint.config.mjs`) + **tsx** for the Mocha suite.

For `@twemoji/parser` (the only runtime dep), read the release notes — URL format changes are breaking.

## Procedure

### 1. Check what's available

```bash
npm run ncu:check
```

Output lists every dep with an upgrade available, respecting `.ncurc.json`. Sample:

```
 @twemoji/parser     17.0.1  →  17.1.0
 typescript           5.9.3  →  5.9.4
 mocha               11.7.5  →  11.8.0
```

### 2. Bump one library at a time

Multi-bumps mask which dependency broke a build. Even if `ncu` proposes ten in one PR, take them one at a time **locally** to isolate breakage; the CI auto-PR can batch.

### 2a. Bump a single dep

```bash
# Edit package.json manually
$EDITOR package.json
# Or use ncu for one specific dep
npx ncu @twemoji/parser -u
# Or for multiple
npx ncu typescript mocha -u
```

Note: `ncu -u` modifies `package.json`. Verify the diff:

```bash
git diff package.json
```

### 2b. Apply via npm install

```bash
npm install
```

This refreshes `node_modules`. There's no committed `package-lock.json`, so the lock is regenerated.

### 3. Run the full check sequence

```bash
npm run eslint:check
npm run prettier:check
npm test
npm run build
npm run build:tsc
```

Read every error. Common failure modes:

| Error                    | Likely cause                                                              |
| ------------------------ | ------------------------------------------------------------------------- |
| `Could not find <coord>` | Wrong package name or version doesn't exist on npm                        |
| `error TS2###:`          | API removed or renamed in the new version (check release notes)           |
| `Module not found: 'X'`  | Package's exports map changed; consumer code needs an updated import path |
| Test snapshot mismatch   | HTML output format changed (Twemoji bump)                                 |
| Lint or format failure   | New `@typescript-eslint` rule was activated                               |

### 4. Address breaking changes

If the new version removed an API:

1. Find the replacement in the release notes
2. Update call sites in `src/` and/or `test/`
3. Re-run the check sequence

If the new version changed default behavior:

- Audit related code paths
- Decide whether to absorb the change or pin back

### 5. Verify the bundle still works

For runtime deps (currently only `@twemoji/parser`):

```bash
npm run build
node -e "console.log(require('./dist/index.js').parse('hello :smile: 🚀'))"
```

Expected: HTML output with valid Twemoji URLs. If the URLs look wrong, the bump changed the URL format — that's a breaking change for consumers. Bump the package's major version.

### 6. Update docs

If the bump:

- **Adds or renames a public API** used in docs → update [`docs/TECHNOLOGIES.md`](../../docs/TECHNOLOGIES.md), [`docs/API_REFERENCE.md`](../../docs/API_REFERENCE.md)
- **Affects the build** (Webpack, ts-loader, ts-node version) → update [`docs/BUILD_DEPLOY.md`](../../docs/BUILD_DEPLOY.md)
- **Affects testing** (mocha, chai) → update [`docs/TESTING_GUIDE.md`](../../docs/TESTING_GUIDE.md)
- **Affects the catalog regeneration** (emojilib, unicode-emoji-json) → update [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) and consider running [`/regenerate-emoji-lib`](regenerate-emoji-lib.md)

Always update [`docs/TECHNOLOGIES.md`](../../docs/TECHNOLOGIES.md) version table for any major bump.

### 7. Commit

```bash
git add package.json
git commit -m "chore: bump <library> to <version>"
```

Conventional commit type:

- `chore:` — routine bump (most common)
- `fix:` — security or bug-fix bump
- `feat:` — bumping unlocks a new feature you're using
- `build:` — toolchain (Webpack, TypeScript, Node)

Examples:

```
chore: bump @twemoji/parser to 17.1.0
fix: bump @types/node to 24.10.3 (CVE-...)
build: bump typescript to 5.9.4
```

## Special cases

### `@twemoji/parser`

The only runtime dependency. Bumps can change:

- **CDN URL format** — historically rare; if it changes, every snapshot test in `main.test.ts` breaks. **Major version bump for our package**
- **Available emojis** — additive; no test breaks
- **Variation selector handling** — sometimes Twemoji decides to render an emoji differently with/without VS-16

After bumping:

```bash
npm test                                   # snapshots will break if URL format changed
npm run build && node -e "console.log(require('./dist/index.js').parse('🚀'))"
```

If snapshots break, decide between:

- **Update snapshots + bump our major** (preferred — consumers need to update their snapshots)
- **Pin Twemoji back** (if the change is undesirable)

### `typescript`

Type-only changes can ripple through the `.d.ts` we ship. After bumping:

```bash
npm run build:tsc                    # check the .d.ts compiles cleanly
npm pack                             # generate a tarball
# install in a sample project to verify types still work for consumers
```

Major TypeScript bumps may shift inferred types in `.d.ts` — review the diff.

### Webpack 5 → 6

Currently we're on Webpack 5. A future Webpack 6 will likely require config changes. When that bump comes, plan to:

1. Bump `webpack` and `webpack-cli` together
2. Audit `webpack.config.js` for deprecated APIs
3. Verify `dist/index.js` still has `module.exports = uEmojiParser` (the dual-export shape depends on `commonjs2`)

### `mocha` major bumps

Mocha occasionally drops Node version support. Verify our `engines.node` is still compatible.

### `node-version` in CI workflows

If we bump `engines.node` in `package.json`, also bump the Node version in every CI workflow:

```yaml
- uses: actions/setup-node@v4
  with:
    node-version: '24'
```

Don't drift CI Node from the package's stated minimum.

## Don't

- ❌ Bump `chai` or `eslint` without lifting `.ncurc.json` exclusions and committing to the migration
- ❌ Bump multiple unrelated libraries in one commit
- ❌ Inline a version in `package.json` `dependencies` to "test it real quick" — always go through `ncu` or manual edit + `npm install`
- ❌ Skip docs updates after a major bump
- ❌ Auto-merge a `@twemoji/parser` bump without reading release notes

## Do

- ✅ Read release notes (at minimum the headline changes)
- ✅ Run all five checks (lint, format, test, build, types) after bumping
- ✅ Update docs in the same commit
- ✅ Use conventional commit messages
- ✅ Treat `@twemoji/parser` URL format changes as breaking (major bump for our package)

## Verification checklist

- [ ] Edited only `package.json` (and re-ran `npm install` to regenerate locks if applicable)
- [ ] `npm run eslint:check` passes
- [ ] `npm run prettier:check` passes
- [ ] `npm test` passes
- [ ] `npm run build` succeeds
- [ ] `npm run build:tsc` succeeds (types compile)
- [ ] If `@twemoji/parser` was bumped, manual smoke-test of HTML output succeeded
- [ ] Docs updated for any documented version
- [ ] Conventional commit message