Dependencies Upgrade Plan

Summary of Dependency Upgrade Plan

Phase	Groups
1	Minor/patch: shelljs, object.assign, mkdirp, node-plop, microbundle, cspell*, copy, semver, axios, ejs, typedoc, tsdx, etc.
2	Babel (@babel/*, babel-*, etc.), ESLint (eslint, eslint-plugin-*, etc.), TypeScript (typescript, @typescript-eslint/*), plus commitlint/changesets/husky.
3	React 17 → 18 (plus @types/react and any React peerDeps that need updating).
4	Testing Infrastructure: Jest (jest, babel-jest, etc.) + @testing-library/* after React 18.
5	Storybook (@storybook/react, @storybook/addon-*), UI libs (victory, @carbon/charts-react, etc.).
6	Gatsby 3.x → 5.x + official plugins.
7	Cleanup: remove unnecessary polyfills, finalize codebase refactors, etc.

Related Issues

Phase	Task	GitHub Issue #
Phase 1: Prep & Low-Risk Minor/Patch Updates	Upgrade minor/patch dependencies	#1642
Phase 2: Babel, ESLint & TypeScript (Pre-React)	Upgrade Babel dependencies	#1643
Phase 2: Babel, ESLint & TypeScript (Pre-React)	Upgrade ESLint & TypeScript dependencies	#1644
Phase 2: Babel, ESLint & TypeScript (Pre-React)	Upgrade commitlint, changesets, and husky	#1645
Phase 3: React 17 → React 18	Upgrade React to version 18	#1646
Phase 4: Testing Infrastructure (Post-React 18)	Upgrade Jest & Testing Library	#1647
Phase 5: Storybook & UI Libraries	Upgrade Storybook to latest version	#1648
Phase 6: Gatsby & Major Bundlers	Upgrade Gatsby to version 5	#1650

Phase 1: Prep & Low-Risk Minor/Patch Updates

Goal: Update packages that typically do not introduce significant breaking changes.

Dependency	Current	Target	Notes
shelljs	0.8.5	Latest patch if any	Low risk – used for scripting.
object.assign	4.1.5	^4.1.7 or remove	Modern JS + Babel can often eliminate the need for this polyfill.
mkdirp	1.0.4	^1.0.4 or ^3.x	3.x is a major bump; check migration notes.
node-plop	0.26.3	^0.32.x (minor/patch)	Typically minimal breaking changes.
microbundle	0.13.3	^0.15.x (minor/patch)	Ensure existing build scripts remain compatible.
cspell	4.2.8	^4.x or ^5.x	Keep cspell-dict-* dictionaries aligned if possible.
cspell-dict-es-es	1.1.2	Next patch/minor	Dictionary only; minimal risk.
cspell-dict-lorem-ipsum	1.1.2	Next patch/minor	Same as above.
copy	0.3.2	Next patch/minor	Used for file copying tasks.
semver	7.3.5	Latest patch/minor	Low risk for normal version range calculations.
axios	1.7.8	Latest patch/minor	If only minor/patch is available.
ejs	3.1.10	Latest patch/minor	Template engine. Typically safe to bump minor/patch.
regenerator-runtime	0.13.11	^0.14.x (if feasible)	Ensure Babel usage remains consistent.
typedoc	0.19.2	Next minor/patch in 0.x	May require bigger step.
tsdx	0.14.1	Latest patch/minor	Generally stable for library packaging.

Action Items

1. Branch: chore/deps-prep-minor
2. Upgrade each package to its safe minor/patch release.
3. Test, build, run lint, and do minimal QA.
4. Merge once stable.

---

Phase 2: Babel, ESLint & TypeScript (Pre-React)

Goal: Upgrade build and lint tooling before React or testing libraries. This ensures code can compile cleanly and pass stricter lint rules under modern tooling.

Babel Packages

Dependency	Current	Target	Notes
@babel/cli	7.17.0	^7.28.x or latest	Keep all Babel packages in sync (same minor if possible).
@babel/core	7.24.5	^7.28.x	Major is still 7; just a higher minor/patch.
@babel/plugin-proposal-class-properties	7.16.7	^7.28.x	Also update other @babel/plugin-proposal-*.
@babel/plugin-proposal-export-default-from	7.16.7	^7.28.x
@babel/plugin-proposal-export-namespace-from	7.16.7	^7.28.x
@babel/plugin-proposal-object-rest-spread	7.16.7	^7.28.x
@babel/plugin-proposal-throw-expressions	7.16.7	^7.28.x
@babel/plugin-syntax-import-meta	7.10.4	^7.28.x	Minor updates typically.
@babel/preset-env	7.24.5	^7.28.x	Check target browsers in .babelrc or babel.config.js.
@babel/preset-react	7.16.7	^7.28.x	Will help once we get to React 18.
@babel/preset-typescript	7.24.1	^7.28.x	Integrates with TypeScript below.
babel-core (bridge)	7.0.0-bridge.0	Potential removal	keep it pinned or remove if no longer needed.
babel-eslint	10.1.0	Consider removing	Often replaced by @babel/eslint-parser or integrated approach with TypeScript.
babel-plugin-dynamic-import-node	2.3.3	Latest patch/minor	If still needed for SSR or Node, keep it updated.
babel-plugin-polished	1.1.0	Latest patch/minor	If we rely on polished in Babel transforms.

ESLint & TypeScript

Dependency	Current	Target	Notes
eslint	7.32.0	^9.x	Check .eslintrc for rule changes.
eslint-plugin-import	2.25.4	Next stable 2.x	Update if new minor is out.
eslint-plugin-jest	24.7.0	Next stable	Minor/patch if no major bump.
eslint-plugin-jsx-a11y	6.5.1	Next stable 6.x	A11y checks.
eslint-plugin-mdx	3.1.5	Next stable 3.x
eslint-plugin-prettier	5.2.1	Next stable 5.x	Keep in sync with Prettier version.
eslint-plugin-react	7.34.3	Next stable 7.x	Might see new rules for React.
eslint-plugin-react-hooks	4.3.0	Next stable 4.x	Further updates might be minor.
eslint-plugin-unicorn	22.0.0	Next stable	Usually safe to bump in minor/patch.
eslint-config-cengage	2.1.4	Next patch if any	Internal config.
eslint-config-prettier	7.2.0	^10.x	Align with latest Prettier major if relevant.
@typescript-eslint/parser	4.33.0	^8.x	Must match TS version.
@typescript-eslint/eslint-plugin	4.33.0	^8.x	Same as above.
typescript	3.9.10	^5.x	Expect stricter checks, new types.

Commitlint, Changesets, and Related

Dependency	Current	Target	Notes
@commitlint/cli	11.0.0	Next major/minor	Possibly 16+ now; see official docs.
@commitlint/* packages (config-conventional, is-ignored, parse, etc.)	11.x / 12.x range	Next stable	Keep consistent versions across them.
@changesets/cli	2.20.0	Next stable 2.x	If new minor available, update.
@changesets/changelog-github	0.4.2	^0.5.x	For GH changelog integration.
commitizen	4.2.5	Next stable 4.x	Minor/patch.
conventional-changelog-cli	2.2.2	Next stable	Potentially 3+ or 5+ depending on release.
conventional-changelog-conventionalcommits	4.6.3	Next stable	Matches new commitlint.
cz-conventional-changelog	3.3.0	Next stable 3.x	Typically minimal risk.
husky	6.0.0	^9.x	Hook runner. Major changes in config style.

Action Items

1. Branch: chore/deps-babel-eslint-ts
2. Bump all Babel packages (synchronously) to the same minor range.
3. Upgrade ESLint core, plugins, Prettier, TypeScript.
4. Update commitlint & changesets if desired.
5. Fix or suppress new lint/type errors.
6. Merge once stable.

---

Phase 3: React 17 → React 18

Goal: Now that build/lint tooling is modernized, perform the critical jump to React 18. Testing libraries still remain on hold until after React is upgraded.

Dependency	Current	Target	Notes
react	17.0.2	^18.x	Override any suggestion for React 19.
react-dom	17.0.2	^18.x	Must match React version exactly.
react-test-renderer	17.0.2	^18.x	Snapshot testing if used (though final testing upgrades in Phase 4).
@types/react	16.14.23	^18.x	Sync TypeScript definitions with React 18.
Any React-dependent libs in monorepo (e.g., @emotion/react, @emotion/styled, downshift, react-dropzone, etc.)	Update to a React 18–compatible version if needed. Check peerDependencies to avoid conflicts.

Action Items

1. Branch: chore/deps-react18
2. Force react, react-dom to ^18.x across all sub-packages.
3. Update @types/react to ^18.x.
4. Verify any libraries that specify peerDeps of "react": "^17 || ^18". Most will still work fine once we bump them to the latest minor.
5. If desired, refactor to ReactDOM.createRoot for concurrency features or keep ReactDOM.render.
6. Merge once baseline UI checks pass.

---

Phase 4: Testing Infrastructure (Post-React 18)

Goal: Now that React 18 is established, we can safely upgrade testing libraries (which require React 18 for the newest versions).

Dependency	Current	Target	Notes
jest	26.6.3	^29.x or latest 29	If not already upgraded in Phase 2, do so here.
babel-jest	26.6.3	Must match Jest	Typically pinned to same major as Jest (29.x).
@testing-library/react	11.2.7	^16.2.0+	Now valid since we're on React 18.
@testing-library/dom	7.31.2	Next stable	Check for peerDeps requiring React 18.
@testing-library/jest-dom	5.16.2	Next stable 6.x	Usually works with any modern React but see release notes.
@testing-library/react-hooks	7.0.2	Next stable 8.x	Might require React 18.
@testing-library/user-event	13.5.0	Next stable 14.x	See release notes for any React 18 concurrency changes.
jest-axe	5.0.1	Next stable 9.x	Evaluate if it has new peerDeps.
jest-extended	0.11.5	Next stable 4.x	Possibly a big jump; check for major changes.
jest-watch-typeahead	0.6.5	Next stable 2.x	Align with Jest 29 if needed.
jest-dom	4.0.0	Newer versions moved into @testing-library/jest-dom but if still used, check updates.

Action Items

1. Branch: chore/deps-testing-infra
2. Confirm or finalize Jest version if not fully updated in Phase 2.
3. Upgrade @testing-library/react to ^16.2.0 or the latest that supports React 18.
4. Update any other testing-related packages.
5. Rerun all tests to confirm no breakages from concurrency or new library APIs.
6. Merge once all tests pass.

---

Phase 5: Storybook & UI Libraries

With React 18 and testing in place, upgrade Storybook (6.5.x → 7/8) and any UI libraries not yet updated.

Dependency	Current	Target	Notes
@storybook/react	6.5.16	^7.x or ^8.x	Check the official SB docs for migration steps.
@storybook/addon-*	6.5.x range	^7.x or ^8.x	Must match main Storybook version. Actions, docs, controls, measure, toolbars, etc.
victory	35.11.4	^37.x	If used in stories, confirm React 18 support.
@carbon/charts-react	1.22.0	If newer minor	Check for any React 18–related updates if used in SB stories.

Action Items

1. Branch: chore/deps-storybook
2. Update @storybook/react plus relevant add-ons in lockstep (e.g., all to 7.x or 8.x).
3. Migrate story formats if we use old storiesOf; recommended to switch to CSF.
4. Validate local dev via npm run storybook (or equivalent).
5. Merge once we confirm stable usage and add-on compatibility.

---

Phase 6: Gatsby & Major Bundlers

Lastly, for the docs site (or other Gatsby-based sites), move from Gatsby 3 → 5. This can involve SSR changes, plugin updates, and a new image pipeline.

Dependency	Current	Target	Notes
gatsby	3.15.0	^5.x	Big jump. Read 3→4→5 migration docs.
gatsby-plugin-manifest	3.15.0	^5.x	Must match Gatsby major.
gatsby-plugin-mdx	2.15.0	^5.x	SSR and MDX changes possible.
gatsby-plugin-offline	4.15.0	^6.x or ^5.x if that’s the matching version	Usually updates in lockstep with Gatsby major.
gatsby-plugin-react-helmet	4.15.0	^6.x	Might not be needed if Gatsby supplies built-in helmet alternatives.
gatsby-plugin-sharp	3.15.0	^5.x	For image processing – significant changes.
gatsby-remark-images	4.2.0	^7.x	Keep in sync with new Gatsby image pipeline.
gatsby-source-filesystem	3.15.0	^5.x	Standard FS source plugin.
gatsby-transformer-sharp	3.15.0	^5.x	Tied to Gatsby’s new image pipeline.
react-helmet	5.2.0	^6.x	If we rely on react-helmet externally.

Action Items

1. Branch: chore/deps-gatsby5
2. Upgrade gatsby core + plugins to 5.x, verifying each plugin is actively maintained.
3. Check for SSR changes, environment variable usage, or GraphQL schema updates.
4. gatsby develop / gatsby build and test the site thoroughly.
5. Merge once we confirm no critical regressions.

---

Phase 7: Cleanup & Optional Refactors

After major versions are settled:

1. Remove Polyfills: If no longer needed (e.g., object.assign, or leftover core-js usage).
2. Modernize React Code: Replace older lifecycle methods with hooks or concurrency-friendly approaches.
3. Refine TypeScript Config: Possibly enable stricter settings (strictNullChecks, noImplicitOverride, etc.).
4. Final QA: Confirm everything runs smoothly in a staging or production-like environment.