OpenNoodl/dev-docs/tasks/phase-1-dependency-updates/TASK-001-dependency-updates/README.md

TASK-001: Dependency Updates & Build Modernization

Metadata

Field	Value
ID	TASK-001
Phase	Phase 1 - Foundation
Priority	🔴 Critical
Difficulty	🟡 Medium
Estimated Time	2-3 days
Prerequisites	None (this is the first task)
Branch	task/001-dependency-updates
Related Branches	12-upgrade-dependencies (previous dev work)

Objective

Complete and validate all dependency updates, fully migrate to React 19, and modernize the build pipeline for reliable, fast development.

Background

A previous developer started this work on the 12-upgrade-dependencies branch. They updated package.json files across the monorepo, including:

• React 17 → 19
• Various webpack, typescript, and tooling updates
• Removed Node.js version upper cap

They also made a commit "Update rendering to use non-deprecated react-dom calls" which addressed some React 19 breaking changes.

This task completes that work, validates everything works, and improves the overall build experience.

Current State

What Exists

• Branch 12-upgrade-dependencies with package.json updates
• Some React 19 migration work done
• Build may have errors or warnings

Known Issues

• react-instantsearch-hooks-web renamed to react-instantsearch (breaking API change)
• ReactDOM.render() deprecated in React 18+
• Potential peer dependency conflicts
• Hot reload may be unreliable
• Build times are slow

Key Package Changes (from previous dev)

Package	Old	New	Breaking Changes
react	17.0.2	19.0.0	Yes - see below
react-dom	17.0.0	19.0.0	Yes - render API
react-instantsearch-hooks-web	6.38.0	react-instantsearch 7.16.2	Yes - renamed
webpack	5.74.0	5.101.3	Minor
typescript	4.8.3	4.9.5	Minor

Desired State

After this task:

• All packages build without errors
• No deprecation warnings in console
• React 19 fully adopted (no legacy patterns)
• Hot reload works reliably
• Build completes in <60 seconds
• All existing tests pass

Scope

In Scope

• Validate and fix dependency updates
• Complete React 19 migration
• Fix all build errors and warnings
• Update react-instantsearch usage
• Improve build performance
• Fix hot reload issues

Additional Items from TASK-000 Analysis

Based on TASK-000 Dependency Analysis, the following items should be added:

🔴 P0 - Critical (Added) ✅ COMPLETED

• Fix Storybook scripts in noodl-core-ui - Updated to Storybook 8.6.14 with modern CLI commands
• Standardize TypeScript version - noodl-viewer-react updated to 4.9.5 to match rest of monorepo

🟡 P1 - High Priority (Added) ✅ COMPLETED

• Update webpack plugins in noodl-viewer-react:
  • copy-webpack-plugin 4.6.0 → 12.0.2
  • clean-webpack-plugin 1.0.1 → 4.0.0 (replaced with output.clean)
  • webpack-dev-server 3.11.2 → 4.15.2
• Align css-loader (5.0.0 → 6.11.0) and style-loader (2.0.0 → 3.3.4) in noodl-viewer-react
• Update Jest to v29 across all packages (jest 29.7.0, ts-jest 29.4.1, @types/jest 29.5.14)
• Update copy-webpack-plugin in noodl-viewer-cloud (4.6.0 → 12.0.2)

🟢 P2 - Nice to Have ✅ COMPLETED

• Update @types/react (19.0.0 → 19.2.7) and @types/react-dom (19.0.0 → 19.2.3)
• Update Babel packages to latest patch versions (already at latest: 7.28.3/7.27.1)

Out of Scope

• Major refactoring (that's later tasks)
• New features
• TSFixme cleanup (TASK-002)
• ESLint 9 migration (significant config changes required)
• Electron upgrade (31 → 39 requires separate planning)
• Express 5.x migration (breaking changes)
• Dugite 3.0 upgrade (breaking API changes)

Technical Approach

Key Files to Modify

File	Changes
package.json (root)	Verify dependencies, fix conflicts
packages/*/package.json	Verify peer deps, fix conflicts
packages/noodl-editor/src/editor/src/views/HelpCenter/HelpCenter.tsx	Update react-instantsearch imports
Any file with ReactDOM.render	Migrate to createRoot
packages/noodl-viewer-react/	React 19 compatibility

React 19 Migration Points

// OLD (React 17)
import ReactDOM from 'react-dom';
ReactDOM.render(<App />, document.getElementById('root'));

// NEW (React 19)
import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(<App />);

Search for these patterns:

grep -r "ReactDOM.render" packages/ --include="*.ts" --include="*.tsx" --include="*.js"
grep -r "ReactDOM.hydrate" packages/ --include="*.ts" --include="*.tsx" --include="*.js"
grep -r "ReactDOM.unmountComponentAtNode" packages/ --include="*.ts" --include="*.tsx" --include="*.js"

react-instantsearch Migration

// OLD
import { InstantSearch, Hits } from 'react-instantsearch-hooks-web';

// NEW
import { InstantSearch, Hits } from 'react-instantsearch';

The API is mostly compatible, but verify all hooks used still exist.

Implementation Steps

Step 1: Setup and Initial Validation

1. Checkout the existing branch: git checkout 12-upgrade-dependencies
2. Create our task branch: git checkout -b task/001-dependency-updates
3. Clean install: rm -rf node_modules && npm install
4. Document any install errors in NOTES.md

Step 2: Fix Dependency Conflicts

1. Run npm install and note all peer dependency warnings
2. For each warning, determine the correct resolution
3. Update package.json files as needed
4. Repeat until npm install runs cleanly

Step 3: Fix Build Errors

1. Run npm run build:editor
2. Fix each error one at a time
3. Document each fix in CHANGELOG.md
4. Repeat until build succeeds

Step 4: React 19 Migration

1. Search for deprecated ReactDOM calls
2. Update each to use createRoot pattern
3. Check for class component lifecycle issues
4. Test each changed component

Step 5: react-instantsearch Update

1. Update imports in HelpCenter.tsx
2. Verify all hooks/components still available
3. Test search functionality

Step 6: Build Optimization

1. Analyze current build time
2. Check webpack configs for optimization opportunities
3. Enable caching if not already
4. Measure improvement

Step 7: Validation

1. Run full test suite
2. Manual testing of key workflows
3. Verify hot reload works
4. Check for console warnings

Testing Plan

Automated Tests

• Run npm run test:editor - all pass
• Run npm run test:platform - all pass
• Run npx tsc --noEmit - no type errors

Manual Testing Scenarios

• Start dev server: npm run dev - starts without errors
• Create new project - works
• Add nodes to canvas - works
• Connect nodes - works
• Preview project - works
• Edit code in Function node - works
• Hot reload when editing - works
• Search in Help Center - works (react-instantsearch)
• Build for production - works

Success Criteria

• npm install completes with no errors
• npm run build:editor completes with no errors
• npm run test:editor all tests pass
• npx tsc --noEmit no TypeScript errors
• No deprecation warnings in browser console
• Hot reload works reliably
• All manual test scenarios pass

Risks & Mitigations

Risk	Mitigation
React 19 breaks something subtle	Extensive manual testing, rollback plan ready
react-instantsearch API changes	Read migration guide, test search thoroughly
Build time regression	Measure before/after, optimize if needed
Peer dependency hell	Use --legacy-peer-deps as last resort, document why

Rollback Plan

If major issues discovered:

1. Checkout main branch
2. Cherry-pick any non-breaking fixes
3. Document issues for future attempt
4. Consider incremental approach (React 18 first, then 19)

References

• React 19 Release Notes
• react-instantsearch v7 Migration
• Previous dev branch: 12-upgrade-dependencies
• Previous dev commit: "Update rendering to use non-deprecated react-dom calls"