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

TASK-001 Changelog

Track all changes made during this task. Update this file as you work.

---

[2025-06-12] - Cline (AI-assisted)

Summary

Fixed React 19 TypeScript compatibility errors that were preventing the build from completing. The previous developer updated dependencies but did not address all the TypeScript compatibility issues with the new @types/react package.

Starting Point

• Based on branch: 12-upgrade-dependencies
• Previous work by: previous developer
• Previous commits include:
  • Package.json dependency updates (React 17 → 19)
  • "Update rendering to use non-deprecated react-dom calls"

---

React 19 TypeScript Fixes

Issue 1: Unused @ts-expect-error directives

React 19's types fixed some underlying issues that were previously suppressed with @ts-expect-error. These now cause errors when the underlying issue no longer exists.

Issue 2: useRef() requires explicit type parameter

In React 19's types, useRef() without a type parameter returns RefObject<unknown>, which is not assignable to more specific ref types.

Fix: Changed useRef() to useRef<HTMLDivElement>(null)

Issue 3: JSX namespace moved

In React 19, JSX is no longer a global namespace. It must be accessed as React.JSX.

Fix: Changed keyof JSX.IntrinsicElements to keyof React.JSX.IntrinsicElements

Issue 4: ReactFragment export removed

React 19 no longer exports ReactFragment. Use Iterable<React.ReactNode> instead.

Issue 5: children not implicitly included in props

React 19 no longer implicitly includes children in component props. It must be explicitly declared.

Fix: Added children?: React.ReactNode to component prop interfaces.

Issue 6: ReactDOM.findDOMNode removed

React 19 removed the deprecated findDOMNode API.

Fix: Access DOM elements directly from refs rather than using findDOMNode.

---

Build Fixes

Error: TS2578: Unused '@ts-expect-error' directive

• Cause: React 19 types fixed the type inference for React.cloneElement()
• Fix: Removed the @ts-expect-error comment
• Files:
  • packages/noodl-core-ui/src/components/layout/Columns/Columns.tsx
  • packages/noodl-viewer-react/src/components/visual/Columns/Columns.tsx

Error: TS2554: Expected 1 arguments, but got 0 (useRef)

• Cause: React 19's types require an initial value for useRef()
• Fix: Added type parameter and null initial value: useRef<HTMLDivElement>(null)
• Files:
  • packages/noodl-core-ui/src/components/app/SideNavigation/SideNavigation.tsx
  • packages/noodl-core-ui/src/components/popups/ContextMenu/ContextMenu.tsx

Error: TS2322: RefObject not assignable to RefObject

• Cause: Untyped useRef() returns RefObject<unknown>
• Fix: Same as above - add explicit type parameter
• Files: Same as above

Error: TS2305: Module 'react' has no exported member 'ReactFragment'

• Cause: ReactFragment was removed in React 19
• Fix: Replaced with Iterable<React.ReactNode>
• File: packages/noodl-viewer-react/src/types.ts

Error: TS2503: Cannot find namespace 'JSX'

• Cause: JSX is no longer a global namespace in React 19
• Fix: Changed JSX.IntrinsicElements to React.JSX.IntrinsicElements
• Files:
  • packages/noodl-viewer-react/src/components/visual/Group/Group.tsx
  • packages/noodl-viewer-react/src/components/visual/Text/Text.tsx

Error: TS2339: Property 'children' does not exist on type

• Cause: React 19 no longer implicitly includes children in props
• Fix: Added children?: React.ReactNode to component interfaces
• Files:
  • packages/noodl-viewer-react/src/components/visual/Drag/Drag.tsx
  • packages/noodl-viewer-react/src/components/visual/Group/Group.tsx

Error: Property 'findDOMNode' does not exist on ReactDOM

• Cause: findDOMNode removed from React 19
• Fix: Access DOM element directly from ref instead of using findDOMNode
• File: packages/noodl-viewer-react/src/components/visual/Group/Group.tsx

---

Files Modified

• packages/noodl-core-ui/src/components/layout/Columns/Columns.tsx
• packages/noodl-core-ui/src/components/app/SideNavigation/SideNavigation.tsx
• packages/noodl-core-ui/src/components/popups/ContextMenu/ContextMenu.tsx
• packages/noodl-viewer-react/src/types.ts
• packages/noodl-viewer-react/src/components/visual/Columns/Columns.tsx
• packages/noodl-viewer-react/src/components/visual/Drag/Drag.tsx
• packages/noodl-viewer-react/src/components/visual/Group/Group.tsx
• packages/noodl-viewer-react/src/components/visual/Text/Text.tsx

---

Files Created

• None

---

Files Deleted

• None

---

Breaking Changes

• React 19 requires Node.js 18+ (documented in root package.json engines)
• findDOMNode usage removed - code now accesses refs directly

---

Testing Notes

Automated Tests

• npm run dev: PASS - All three packages (Editor, Viewer, Cloud) compile successfully

Manual Tests

• Dev server start: PASS - Editor launches, Viewer compiles, Cloud compiles

---

Known Issues

1. Deprecation warnings for Sass legacy JS API - Non-blocking, can be addressed in future task
2. Deprecation warning for Buffer() - Non-blocking, comes from dependency

---

Follow-up Tasks

1. Consider updating Sass configuration to use modern API - Future task
2. Review scrollToElement functionality to ensure it works correctly with the new ref-based approach - Manual testing needed

---

Final Summary

Total files modified: 8 Build status: All packages compiling successfully (was 95 errors, now 0) Confidence: 8/10 (code compiles, but manual testing of scrollToElement functionality recommended)

---

[2025-12-07] - Cline (AI-assisted) - P0 Critical Items from TASK-000 Analysis

Summary

Completed the P0 critical items identified in the TASK-000 dependency analysis:

1. Fixed Storybook scripts and dependencies in noodl-core-ui
2. Standardized TypeScript version across packages

---

P0 Item 1: Fix Storybook in noodl-core-ui

Issue

• Old Storybook CLI commands (start-storybook, build-storybook) were being used
• Missing framework-specific packages required for Storybook 8.x
• Configuration file (main.ts) using deprecated format

Changes Made

package.json scripts update

// OLD
"start": "start-storybook -p 6006 -s public",
"build": "build-storybook -s public"

// NEW
"start": "storybook dev -p 6006",
"build": "storybook build"

Added Storybook dependencies

• @storybook/addon-essentials: ^8.6.14
• @storybook/addon-interactions: ^8.6.14
• @storybook/addon-links: ^8.6.14
• @storybook/addon-measure: ^8.6.14
• @storybook/react: ^8.6.14
• @storybook/react-webpack5: ^8.6.14
• Updated storybook from ^9.1.3 to ^8.6.14 (version consistency)

Updated .storybook/main.ts

• Changed from CommonJS (module.exports) to ES modules (export default)
• Added proper TypeScript typing with StorybookConfig
• Updated framework config from deprecated core.builder to modern framework.name format
• Kept custom webpack aliases for editor integration

Files Modified:

• packages/noodl-core-ui/package.json
• packages/noodl-core-ui/.storybook/main.ts

---

P0 Item 2: Standardize TypeScript Version

Issue

• packages/noodl-viewer-react was using TypeScript ^5.1.3
• Rest of the monorepo (root, noodl-core-ui, noodl-editor) uses ^4.9.5
• Version mismatch can cause type compatibility issues

Fix

Changed packages/noodl-viewer-react/package.json:

// OLD
"typescript": "^5.1.3"

// NEW  
"typescript": "^4.9.5"

File Modified:

• packages/noodl-viewer-react/package.json

---

Validation

Build Test

• npm run build:editor:_viewer: PASS ✅
• Viewer builds successfully with TypeScript 4.9.5

Install Test

• npm install: PASS ✅
• No peer dependency errors
• All Storybook packages installed correctly

---

Additional Files Modified (P0 Session)

• packages/noodl-core-ui/package.json - Scripts + Storybook dependencies
• packages/noodl-core-ui/.storybook/main.ts - Modern Storybook 8 config
• packages/noodl-viewer-react/package.json - TypeScript version alignment

---

Notes

Storybook Version Discovery

The storybook CLI package uses different versioning than @storybook/* packages:

• storybook CLI: 9.1.3 exists but is incompatible with 8.x addon packages
• @storybook/addon-*: Latest stable is 8.6.14
• Solution: Use consistent 8.6.14 across all Storybook packages

TypeScript Version Decision

• Chose to standardize on 4.9.5 (matching majority) rather than upgrade all to 5.x
• TypeScript 5.x upgrade can be done in a future task with proper testing
• This ensures consistency without introducing new breaking changes

---

[2025-07-12] - Cline (AI-assisted) - P1 High Priority Items from TASK-000 Analysis

Summary

Completed the P1 high priority items identified in the TASK-000 dependency analysis:

1. Updated webpack plugins in noodl-viewer-react (copy-webpack-plugin, clean-webpack-plugin, webpack-dev-server)
2. Aligned css-loader and style-loader versions
3. Updated Jest to v29 across packages
4. Updated copy-webpack-plugin in noodl-viewer-cloud

---

P1.1: Update Webpack Plugins in noodl-viewer-react

Dependencies Updated

Package	Old Version	New Version
clean-webpack-plugin	^1.0.1	^4.0.0
copy-webpack-plugin	^4.6.0	^12.0.2
webpack-dev-server	^3.11.2	^4.15.2
css-loader	^5.0.0	^6.11.0
style-loader	^2.0.0	^3.3.4
jest	^28.1.0	^29.7.0
ts-jest	^28.0.3	^29.4.1
@types/jest	^27.5.2	^29.5.14

Webpack Config Changes Required

Breaking Change: clean-webpack-plugin v4

• Old API: new CleanWebpackPlugin(outputPath, { allowExternal: true })
• New API: Uses webpack 5's built-in output.clean: true option
• Import changed from require('clean-webpack-plugin') to const { CleanWebpackPlugin } = require('clean-webpack-plugin')

Breaking Change: copy-webpack-plugin v12

• Old API: new CopyWebpackPlugin([patterns])
• New API: new CopyWebpackPlugin({ patterns: [...] })
• transformPath option removed, use to function instead
• Added info: { minimized: true } to prevent Terser from minifying copied JS files

Files Modified:

• packages/noodl-viewer-react/webpack-configs/webpack.viewer.common.js
• packages/noodl-viewer-react/webpack-configs/webpack.deploy.common.js
• packages/noodl-viewer-react/webpack-configs/webpack.ssr.common.js

Webpack Config Migration Example

// OLD (v4.6.0)
const CleanWebpackPlugin = require('clean-webpack-plugin');
const CopyWebpackPlugin = require('copy-webpack-plugin');

new CleanWebpackPlugin(outputPath, { allowExternal: true }),
new CopyWebpackPlugin([
  {
    from: 'static/shared/**/*',
    transformPath: (targetPath) => stripStartDirectories(targetPath, 2)
  }
])

// NEW (v12.0.2)
const CopyWebpackPlugin = require('copy-webpack-plugin');

// output.clean: true in config
output: {
  clean: true
},
new CopyWebpackPlugin({
  patterns: [
    {
      from: 'static/shared',
      to: '.',
      noErrorOnMissing: true,
      info: { minimized: true }
    }
  ]
})

---

P1.2: Update copy-webpack-plugin in noodl-viewer-cloud

Dependencies Updated

Package	Old Version	New Version
copy-webpack-plugin	^4.6.0	^12.0.2
clean-webpack-plugin	(not present)	^4.0.0

Files Modified:

• packages/noodl-viewer-cloud/package.json
• packages/noodl-viewer-cloud/webpack-configs/webpack.viewer.common.js

---

Build Issue: Terser Minification of Copied Files

Problem

When using copy-webpack-plugin v12 with webpack 5 production mode, Terser tries to minify all JS files in the output directory, including copied static files. This caused errors because some copied JS files contained modern syntax.

Solution

Added info: { minimized: true } to CopyWebpackPlugin patterns to tell webpack these files are already minimized and should not be processed by Terser.

{
  from: 'static/deploy',
  to: '.',
  noErrorOnMissing: true,
  info: { minimized: true }  // <-- Prevents Terser processing
}

---

Validation

Build Test

• npm run build:editor:_viewer: PASS ✅
• All three viewer builds (viewer, deploy, ssr) complete successfully

Install Test

• npm install: PASS ✅
• Net reduction of 197 packages (removed 214 old, added 17 new)

---

Files Modified (P1 Session)

noodl-viewer-react

• packages/noodl-viewer-react/package.json - All dependency updates
• packages/noodl-viewer-react/webpack-configs/webpack.viewer.common.js
• packages/noodl-viewer-react/webpack-configs/webpack.deploy.common.js
• packages/noodl-viewer-react/webpack-configs/webpack.ssr.common.js

noodl-viewer-cloud

• packages/noodl-viewer-cloud/package.json
• packages/noodl-viewer-cloud/webpack-configs/webpack.viewer.common.js

---

Summary

P0 + P1 Total files modified: 14 Build status: All packages building successfully ✅ Packages reduced: 197 (cleaner dependency tree with modern versions)

Dependency Modernization Benefits

• Modern plugin APIs with better webpack 5 integration
• Smaller bundle sizes with newer optimizers
• Better support for ES modules and modern JS
• Consistent Jest 29 across all packages
• Removed deprecated clean-webpack-plugin API