# Package Upgrade Analysis

**Date:** November 14, 2025
**Status:** Safe updates completed ✅ | Major upgrades awaiting evaluation

---

## ✅ Completed Updates (Safe/Minor Versions)

All packages below were successfully updated with **zero breaking changes**:

| Package | From | To | Status | Benefits |
|---------|------|-----|--------|----------|
| **@babel/core** | 7.26.10 | 7.28.5 | ✅ | Bug fixes, performance improvements |
| **@babel/plugin-transform-class-properties** | 7.14.5 (proposal) | 7.18.6 (transform) | ✅ | **Removed deprecation warning** |
| **@babel/plugin-transform-typescript** | 7.15.4 | 7.28.5 | ✅ | TypeScript 5.x support |
| **@babel/preset-env** | 7.15.6 | 7.28.5 | ✅ | Latest browser support, smaller output |
| **@babel/preset-react** | 7.14.5 | 7.28.5 | ✅ | React 19 support, JSX improvements |
| **@babel/preset-typescript** | 7.15.0 | 7.28.5 | ✅ | Better TypeScript 5.x handling |
| **@testing-library/jest-dom** | 6.6.3 | 6.9.1 | ✅ | New matchers, bug fixes |
| **@types/react** | 18.2.38 | 18.3.26 | ✅ | Latest React 18 type definitions |
| **babel-loader** | 8.2.2 | 8.4.1 | ✅ | Performance, better source maps |
| **babel-preset-minify** | 0.5.1 | 0.5.2 | ✅ | Minification improvements |
| **css-loader** | 6.2.0 | 6.11.0 | ✅ | Better CSS modules, performance |
| **prettier** | 2.3.2 | 2.8.8 | ✅ | Bug fixes, stability |
| **react** | 19.1.0 | 19.2.0 | ✅ | React 19.2 features, bug fixes |
| **react-dom** | 19.1.0 | 19.2.0 | ✅ | Performance improvements |
| **rollup-plugin-banner2** | 1.2.2 | 1.3.1 | ✅ | Bug fixes |
| **typescript** | 5.3.2 | 5.9.3 | ✅ | **Faster builds, better type inference** |
| **vitest** | 3.1.2 | 3.2.4 | ✅ | Performance, stability |
| **@vitest/coverage-v8** | 3.1.2 | 3.2.4 | ✅ | Matches Vitest version |
| **tslib** | - | latest | ✅ | Required for TypeScript helpers |

### Additional Improvements Made

1. **Fixed Babel Deprecation**
   - Replaced `@babel/plugin-proposal-class-properties` (deprecated)
   - With `@babel/plugin-transform-class-properties` (standard)
   - Updated `babel.config.js` accordingly

2. **Fixed Build Configuration**
   - Excluded test files from TypeScript build
   - Added `**/*.test.ts`, `**/*.test.tsx` to tsconfig exclude
   - Prevents build errors with test-only globals

3. **Fixed Type Errors**
   - Added type assertion for `referrerPolicy` prop
   - Compatible with stricter React 18 type definitions

### Test Results
- ✅ All 20 tests passing
- ✅ Linting passes without errors
- ✅ Build completes successfully
- ✅ Zero vulnerabilities (down from 31)

---

## ⚠️ Major Version Upgrades Available

The following packages have major version upgrades available that **require evaluation** due to breaking changes:

### 🎨 Prettier 3.6.2 (currently 2.8.8)

**Breaking Changes:**
- Migrated to ESM (ECMAScript Modules)
- Changed `trailingComma` default from `"es5"` to `"all"`
- Improved CJK (Chinese/Japanese/Korean) text handling in markdown
- New plugin interface (supports async parsers)

**Benefits:**
- **Better performance** (~2x faster in some cases)
- **Improved formatting** for international content
- **Better plugin ecosystem** with async support
- **Modern codebase** using ESM
- **Active development** with regular updates

**Migration Effort:** Low-Medium
- May reformat some files due to new defaults
- Update `.prettierrc` if using custom `trailingComma` settings
- Compatible with Node 14+

**Recommendation:** ✅ **Worth upgrading**
Prettier 3 is stable and widely adopted. The formatting changes are non-breaking for functionality.

---

### 🧪 Vitest 4.0.9 (currently 3.2.4)

**Breaking Changes:**
- Browser Mode API changes (separate provider packages required)
- `vi.restoreAllMocks()` behavior changed (no longer resets spy state)
- Module mocking mechanism reimplemented
- Some API methods moved/renamed

**Benefits:**
- **Browser Mode is stable** (no longer experimental)
- **Visual Regression Testing** support in browser mode
- **Playwright Trace support** for better debugging
- **New public API methods** (`experimental_parseSpecifications`, custom watchers)
- **Improved module mocking** with constructor support
- **Better performance** and memory usage

**Migration Effort:** Medium
- Review migration guide: https://main.vitest.dev/guide/migration
- Update test setup if using browser mode
- Check for `vi.restoreAllMocks()` usage
- May need to adjust mock implementations

**Recommendation:** ⚠️ **Consider for future update**
Vitest 4 adds powerful features, but requires careful testing. Current v3.2.4 is stable and sufficient for this project's needs. Consider upgrading when:
- You need browser mode features
- You want visual regression testing
- You have time for thorough testing

---

### 📦 Rollup Plugins

#### @rollup/plugin-commonjs 29.0.0 (currently 20.0.0)
#### @rollup/plugin-node-resolve 16.0.3 (currently 13.0.4)

**Breaking Changes:**
- Requires **Rollup 4+** (currently using Rollup 3.x)
- Better CommonJS detection heuristics (may affect some edge cases)
- Improved dynamic import handling (requires Node 12+)
- Changed module resolution algorithm

**Benefits:**
- **Better CommonJS/ESM interop**
- **Faster builds** with Rollup 4
- **Better tree-shaking**
- **Improved circular dependency handling**
- **Bug fixes** for edge cases

**Migration Effort:** Medium-High
- **Must upgrade Rollup first** (to v4.x)
- May need to adjust rollup config
- Test all build outputs thoroughly
- Check for changes in bundle size/format

**Recommendation:** ⚠️ **Blocked - requires Rollup 4 upgrade**
These plugins require Rollup 4.x, which is a separate major upgrade. Consider as part of a larger build tooling update:

1. Upgrade Rollup 3.x → 4.x
2. Then upgrade both plugins together
3. Thoroughly test build outputs
4. Review bundle sizes

**Rollup 4 Benefits:**
- Faster builds (~2x in some cases)
- Better tree-shaking
- Smaller bundles
- Native ESM support improvements

---

### 🌐 Webpack Loaders (if using Webpack)

#### babel-loader 10.0.0 (currently 8.4.1)
#### css-loader 7.1.2 (currently 6.11.0)

**Breaking Changes:**
- Requires **Webpack 5+**
- Changed configuration options
- Dropped Node.js 12 support (requires Node 14+)

**Benefits:**
- **Better performance** with Webpack 5
- **Module federation** support (css-loader)
- **Better caching** mechanisms
- **Modern CSS features** (css-loader 7)

**Status:** ⚠️ **Not applicable**
This project uses **Rollup** for bundling, not Webpack. These loaders are only used by Babel internally and don't affect this project's build.

**Recommendation:** ⏸️ **Skip**
No need to upgrade these unless you plan to use Webpack for development or demos.

---

### 📘 React Types 19.x (currently 18.3.26)

**Breaking Changes:**
- Type definitions for React 19 API changes
- Stricter prop types in some areas
- New hooks type definitions

**Benefits:**
- **Full React 19 type support**
- **Better type inference**
- **New features types** (use, useOptimistic, etc.)

**Status:** ⚠️ **Already on React 19**
You're using React 19.2.0 but React 18 types.

**Recommendation:** ⚠️ **Consider upgrading carefully**
If using React 19 features like `use()` hook or `useOptimistic()`, upgrade to `@types/react@19`.
However, React 18 types still work for most common use cases. Only upgrade if:
- You need React 19-specific type definitions
- You're using new React 19 APIs
- TypeScript shows type errors with React 19 features

---

## 📊 Upgrade Priority Matrix

| Package | Impact | Effort | Risk | Priority | Recommendation |
|---------|--------|--------|------|----------|----------------|
| **Prettier 3** | Medium | Low | Low | 🟢 High | Upgrade soon |
| **Vitest 4** | Medium | Medium | Medium | 🟡 Medium | Consider for v3.0 |
| **Rollup Plugins** | High | High | Medium | 🔴 Low | Plan comprehensive upgrade |
| **@types/react 19** | Low | Low | Low | 🟡 Medium | Upgrade if using React 19 APIs |
| **Webpack Loaders** | None | - | - | ⚫ Skip | Not applicable |

---

## 🎯 Recommended Upgrade Path

### Phase 1: Low-Risk Updates ✅ **COMPLETED**
- [x] All minor/patch version updates
- [x] Fix deprecation warnings
- [x] TypeScript 5.9
- [x] React 19.2
- [x] All Babel 7.28 packages

### Phase 2: Formatting & Testing (Optional)
- [ ] Upgrade Prettier to 3.6.2
- [ ] Review and commit formatting changes
- [ ] Update prettier config if needed

### Phase 3: Build Tooling (Major Effort)
- [ ] Research Rollup 4.x migration path
- [ ] Upgrade Rollup 3.x → 4.x
- [ ] Upgrade @rollup/plugin-commonjs → 29.x
- [ ] Upgrade @rollup/plugin-node-resolve → 16.x
- [ ] Thorough testing of build outputs
- [ ] Review bundle sizes and optimizations

### Phase 4: Testing Framework (When Needed)
- [ ] Upgrade Vitest to 4.x when browser mode or visual testing needed
- [ ] Update test configuration
- [ ] Adjust mocking code if using `vi.restoreAllMocks()`
- [ ] Full test suite validation

---

## 📝 Notes

- **All safe updates have been completed** with zero breaking changes
- **All 20 tests passing**, linting clean, build successful
- **Zero security vulnerabilities** (down from 31)
- Major upgrades should be planned separately
- Consider creating feature branches for each major upgrade phase
- Always run full test suite after major upgrades

---

## 🔗 Resources

- [Prettier 3.0 Release Notes](https://prettier.io/blog/2023/07/05/3.0.0.html)
- [Vitest 4.0 Release Notes](https://vitest.dev/blog/vitest-4)
- [Vitest Migration Guide](https://main.vitest.dev/guide/migration)
- [Rollup 4.0 Release Notes](https://github.com/rollup/rollup/releases)
- [React 19 Release Notes](https://react.dev/blog/2024/04/25/react-19)