PIE Aperture - A build bug that occured overnight and how we debugged it!

[siggerzz]

Overview

@JoshuaNg2332 and myself recently worked in PIE Aperture to add a basic WebDriverIO test framework to allow us to test the integration of our PIE web components.

Things were going smoothly with our branch. The tests were created, passing against the deployed applications.

but then...

seemingly overnight, running yarn build for the Next app resulted in the following issue:

$ next build
- info Linting and checking validity of types  
- info Creating an optimized production build  
- info Compiled successfully
- info Collecting page data ...TypeError: Cannot redefine property: size
    at defineProperty (<anonymous>)
    at n.createProperty (file:///Users/ben.siggery/Code/pie-aperture/nextjs-app/node_modules/@lit/reactive-element/node/reactive-element.js:1:1332)
    at file:///Users/ben.siggery/Code/pie-aperture/nextjs-app/node_modules/@lit/reactive-element/node/decorators/property.js:6:682
    at file:///Users/ben.siggery/Code/pie-aperture/nextjs-app/node_modules/@lit/reactive-element/node/decorators/property.js:6:769
    at s (/Users/ben.siggery/Code/pie-aperture/nextjs-app/.next/server/chunks/485.js:51:29)
    at /Users/ben.siggery/Code/pie-aperture/nextjs-app/.next/server/chunks/485.js:89:1

> Build error occurred
Error: Failed to collect page data for /components
    at /Users/ben.siggery/Code/pie-aperture/nextjs-app/node_modules/next/dist/build/utils.js:1158:15 {
  type: 'Error'
}
error Command failed with exit code 1.

Troubleshooting attempt - PIE Button

Initially, we suspected given the references to the @lit-labs namespace in the stacktrace, the issue could've been caused by PIE Button, as early in the PR, we decided to bump @justeattakeaway/pie-button from 0.28 => 0.34.

Looking at the PIE Button changelog though, no changes looked suspect:

*0.34.0*
[Fixed] - Set explicit height and fix xsmall and small bg colors

*0.33.0*
[Added] - @tagname jsdoc comment to top of component class and use new defineCustomElement function to define the components

*0.32.0*
[Added] - Native form submit and reset handling logic to pie-button

*0.31.0*
[Fixed] - License removed from packages

*0.30.0*
[Added] - set sideEffects package.json property to correctly communicate to bundlers such as webpack that js files in the component dist folders contain side effects and should therefore not be treeshaken when the entire library is imported.
[Changed] - Align author field for all packages


*0.29.0*
[Changed] - Use pie-css to handle focus styling

**0.28.1**
[Changed] - add missing peer dependencies
[Changed] - update packages, including @babel/core and @justeat/pie-design-tokens

Troubleshooting attempt - yarn.lock

After concluding that the issue wasn't related to PIE Button, we decided revert our branch to earlier commits, to see if we could get the NextJS test app to build.

After reverting to this commit, we were able to successfully build the NextJS app. However, when we deleted our yarn.lock file and re-ran yarn, there were changes to the file, and the app would no longer build successfully, and always resulted in the stacktrace shown above.

Looking at the following commit, we are able to see changes related to @lit-labs/** packages.

Working yarn.lock (simplified version)

Broken yarn.lock

Upon further inspection, we can see the following:

1) The NextJS Application in PIE Aperture has a direct dependency of @lit-labs/nextjs

We pin the version to 0.1.2, meaning that whatever the problem is, it's happening further down the dependency tree.

2) Looking in the @lit-labs/nextjs package.json, we see a dependency of @lit-labs/ssr-react

While we can see this dependency in the yarn.lock visualisations above, it's worth taking a look at the @lit-labs/nextjs package.json to see how it's resolved, as we can see, @lit-labs/ssr-react has somehow changed from 0.2.0 => 0.2.1.

From here, we can see that @lit-labs/nextjs specifies 0.2.0 as the compatible version of the srr-react package OR any newer minor / patch versions (denoted by the ^).

  "dependencies": {
    "@lit-labs/ssr-react": "^0.2.0",
    ...
  },

At this point we have something to go off, and you may have figured out what the cause is...

4) Lets head over to npm and see when ssr-react was last updated...

Looks suspiciously close to the timeframe in which we started encountering build issues...

5) Going back to our yarn.lock visualisation, we see. our smoking gun. The Lit dependency has changed from 2.x => 3.x.

Let's test our theory, and use the resolutions feature in node to force yarn to resolve specific versions, rather than letting yarn take into consideration the ^ that's defined by some of the @lit-labs packages.

// nextjs-app package.json
  "resolutions": {
    "@lit-labs/ssr-react": "0.2.0",
    "@lit-labs/ssr": "3.1.0",
    "@lit-labs/ssr-client": "1.1.0",
    "lit": "2.7.0"
  }

yarn run v1.22.19
$ next build
- info Linting and checking validity of types  
- info Creating an optimized production build  
- info Compiled successfully
- info Collecting page data  
- info Generating static pages (4/4)
- info Finalizing page optimization  

Route (pages)                              Size     First Load JS
┌ ○ /                                      6.33 kB        87.7 kB
├   /_app                                  0 B            81.4 kB
├ ○ /404                                   182 B          81.6 kB
└ ○ /components                            6.18 kB        87.6 kB
+ First Load JS shared by all              91.9 kB
├ chunks/framework-63157d71ad419e09.js   45.2 kB
├ chunks/main-e82deb9dd901341b.js        29.4 kB
├ chunks/pages/_app-5465cd46014a9978.js  5.89 kB
├ chunks/webpack-0b5d8249fb15f5f3.js     939 B
└ css/d402d37a2279885d.css               10.5 kB

○  (Static)  automatically rendered as static HTML (uses no initial props)

✨  Done in 15.47s.

Success!!! 🚀

If there's one thing we learned from this exercise, it's the importance of correct usage of versioning, as well as dependency management.

Even though @lit-labs/ssr-react got bumped to a patch version, for some reason, the version of Lit it depends on was changed by a whole major version!

While ^ may seem like the obvious and inconsequential choice for keeping dependencies up-to-date, since it only updates to new minor / patch versions that're available, you're essentially relying on your dependency maintainers versioning strategy being up to scratch.

In an ideal world, given that the Lit dependency that the @lit-labs packages depend on had been resolving to a new major version, these packages should have been versioned as a new major, to prevent dependants from automatically resolving to the newer version, causing a breaking change.

tl;dr - Be really careful using the ^, especially as a library maintainer