[Bug]: Components from ibm-products library fail to render on serverside on Node v22

[David-Yuen]

Package

Carbon for IBM Products

Description

Using the latest @carbon/ibm-products package, I upgraded our NodeJS from v20.18.0 to v22.13.1 and all components from this ibm-products library fails to render on the server side.
Note that they are working fine in nodeJS v20, but failing in v22.

Specifically, our web application only uses Tearsheet, SidePanel, and EditInPlace components from the ibm-products library. Once i start up our application and try to render a page, the server side render fails with a document is not defined error.
Here is the stack trace:

[2025-02-10T14:44:54.037] [ERROR] Failed to render page: /dashboard?context=cpdaas
Error: Failed to render app on server with exception document is not defined ReferenceError: document is not defined
    at createTag (/Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:30:5)
    at /Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:1316:20
    at /Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:1323:6
    at /Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:1540:4
    at /Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:2:83
    at Object.<anonymous> (/Users/davidyuen/git/lego-ui/node_modules/lottie-web/build/player/lottie.js:5:3)
    at Module._compile (node:internal/modules/cjs/loader:1562:14)
    at Object..js (node:internal/modules/cjs/loader:1699:10)
    at Module.load (node:internal/modules/cjs/loader:1313:32)
    at Function._load (node:internal/modules/cjs/loader:1123:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
    at Module.require (node:internal/modules/cjs/loader:1335:12)
    at require (node:internal/modules/helpers:136:16)
    at Object.<anonymous> (/Users/davidyuen/git/lego-ui/node_modules/@carbon/ibm-products/lib/components/SteppedAnimatedMedia/SteppedAnimatedMedia.js:12:14)
    at Module._compile (node:internal/modules/cjs/loader:1562:14)
    at Object..js (node:internal/modules/cjs/loader:1699:10)
    at Module.load (node:internal/modules/cjs/loader:1313:32)
    at Function._load (node:internal/modules/cjs/loader:1123:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
    at Module.require (node:internal/modules/cjs/loader:1335:12)
    at require (node:internal/modules/helpers:136:16)
    at Object.<anonymous> (/Users/davidyuen/git/lego-ui/node_modules/@carbon/ibm-products/lib/components/CoachmarkOverlayElements/CoachmarkOverlayElements.js:16:28)
    at Module._compile (node:internal/modules/cjs/loader:1562:14)
    at Object..js (node:internal/modules/cjs/loader:1699:10)
    at Module.load (node:internal/modules/cjs/loader:1313:32)
    at Function._load (node:internal/modules/cjs/loader:1123:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
    at Module.require (node:internal/modules/cjs/loader:1335:12)
    at require (node:internal/modules/helpers:136:16)
    at Object.<anonymous> (/Users/davidyuen/git/lego-ui/node_modules/@carbon/ibm-products/lib/index.js:89:32)
    at Module._compile (node:internal/modules/cjs/loader:1562:14)
    at Object..js (node:internal/modules/cjs/loader:1699:10)
    at Module.load (node:internal/modules/cjs/loader:1313:32)
    at Function._load (node:internal/modules/cjs/loader:1123:12)
    at TracingChannel.traceSync (node:diagnostics_channel:322:14)
    at wrapModuleLoad (node:internal/modules/cjs/loader:217:24)
    at Module.require (node:internal/modules/cjs/loader:1335:12)
    at require (node:internal/modules/helpers:136:16)
    at Object.@carbon/ibm-products (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:14853:18)
    at __webpack_require__ (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:15097:41)
    at Object../src/components/Dashboard/DashboardSettings/DashboardSettings.js (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:6215:78)
    at __webpack_require__ (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:15097:41)
    at Object../src/components/Dashboard/DashboardSettings/DashboardSettingsContainer.js (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:6333:76)
    at __webpack_require__ (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:15097:41)
    at Object../src/components/Dashboard/DashboardSettings/index.js (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:6524:85)
    at __webpack_require__ (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:15097:41)
    at Object../src/components/Dashboard/Dashboard.js (/Users/davidyuen/git/lego-ui/build/node/dashboard.js:188:76) 
    at eval (webpack://lego-ui/./src/utils/page-util.js?:71:14)
    at ReactExpressView._render [as engine] (webpack://lego-ui/./src/utils/ssr-util.js?:83:5)
    at ReactExpressView.render (webpack://lego-ui/./src/server/express-view.js?:16:10)
    at tryRender (/Users/davidyuen/git/lego-ui/node_modules/express/lib/application.js:657:10)
    at Function.render (/Users/davidyuen/git/lego-ui/node_modules/express/lib/application.js:609:3)
    at ServerResponse.render (/Users/davidyuen/git/lego-ui/node_modules/express/lib/response.js:1049:7)
    at _renderPage (webpack://lego-ui/./src/utils/page-util.js?:68:7)
    at eval (webpack://lego-ui/./src/utils/page-util.js?:40:5)
    at processTicksAndRejections (node:internal/process/task_queues:105:5)

All 3 of these components throw the same error. So from what I can tell, Tearsheet, SidePanel, and EditInPlace imports/inherits/uses CoachmarkOverlayElements -> SteppedAnimatedMedia -> lottie/lottie-web, which the lottie library seems to be the source of the crash error based on the stack trace.. I assume all components from the ibm-products library (or at least, all components who also import/use these shared libraries) are also affected.

I narrowed it down by commenting out all the import and rendering of @carbon/ibm-products related components.. and then the server side rendering succeeded and started working as normal. So this is proof and evidence that the root cause of the problem is here.

For example, if components has something like:

import { Tearsheet } from "@carbon/ibm-products";

...

render() {
  return (
    <>
      <div>Our other stuff</div>
      <Tearsheet> .. </Tearsheet>
    </>
  );
}

and then i commented out ONLY components from ibm-products library, like:

//import { Tearsheet } from "@carbon/ibm-products";

...

render() {
  return (
    <>
      <div>Our other stuff</div>
      {/* <Tearsheet> .. </Tearsheet> */}
    </>
  );
}

Then I rebuild our application and start.. and everything starts working again. Both server side rendering and rendering on the browser runs normally.

Component(s) impacted

In our product, we only use Tearsheet, SidePanel, and EditInPlace components from the @carbon/ibm-products library, and it's affecting all 3 of these components for sure. But I'm assuming it affects all components from the ibm-products library that import/use lottle/lottie-web (which is used in the SteppedAnimatedMedia)..

Browser

Chrome

@carbon/ibm-products (previously @carbon/ibm-cloud-cognitive) version

2.59.0

Suggested Severity

Severity 1 = The design is broken in a critical way that blocks users from completing tasks or damages the brand. Affects major functionality, no workaround.

Product/offering

Data Replication

CodeSandbox or Stackblitz example

N/A

Steps to reproduce the issue (if applicable)

No response

Release date (if applicable)

No response

Code of Conduct

• I agree to follow this project's Code of Conduct
• I checked the current issues for duplicate issues

[David-Yuen]

I did look at the existing issues in the ibm-products repo, these issues might be related:

#4185
There's no details in this issue, and I didnt test node v21 specifically, but it's possible v21 and v22 have similar design and detects the same errors..

#6201
This may also be related, i dont know if decoupling will resolve the SSR issue or not.. this ticket was originally addressing some other packaging/performance issue.

[David-Yuen]

Also important to mention is, we're asked to upgrade to Node v22 because v20 has security vulnerabilities, and Node v20 is now in maintenance mode.

[David-Yuen]

On the ibm-products slack channel, I also did find this thread: https://ibm-analytics.slack.com/archives/C013ZTX0N6B/p1732703674757719

This seems to be someone who found the same problem but this was a few months ago.. The most recent comments on that thread was that there wasn't much the ibm-products team could do but wait for lottie/lottie-web/lottie-svelte (these libraries were mentioned in the thread but i dont know which ones really apply..) libraries fixes the issues..
I did look at the referenced issues, but it seems like they arn't going to do anything about this.. it's been several months already and no activity on those..

If that 6201 issue to decouple the lottie related packages, as in removing them from the ibm-products library, this would be preferred so that we can get going and upgrade to node v22, instead of waiting on those other 3rd party libraries that seem to have gone stale in relation to this issue.

[anamikaanu96]

We are working on it and it should be available in an upcoming release. #6434 should be the last issue to fully remove it.

[Mikadv]

We have the same issue. Our SSR is now broken because of this.