migrate build tooling from webpack to Vite

[aqandrew]

Dependency

• need to complete Modify CheckEnv.js to notify dev if Vite keys are missing from .env file #1824

Overview

We'd like to propose an alternative build tool in order to make it easier to implement tests for our frontend testing framework

More Info (optional)

Vite is a popular open-source frontend build tool that offers HMR (hot module reloading), which means that saving changes to files during development can update the dev server almost instantly (< 50 milliseconds, source).

Hey team, I've made progress on the testing ticket #1334 (and got some unit tests working), but I've been having some difficulty configuring Babel/Jest to run further tests.

In my experience, Vite/Vitest are much simpler to set up than webpack/Jest. I got curious and wanted to see if I could replace webpack in our repo with Vite. I managed to get HMR working in about half an hour (see screen recording below!) and figured this would improve everyone's developer experience a lot.

@ryanfchase I'd like to propose deprioritizing tests in favor of upgrading our build tooling. This would be a huge win for a lot less effort, and as a bonus it will become easier to implement tests.

Action Items

• install Vite package
• get MVP Vite dev server running
  • rename .js files to .jsx if they contain JSX
• port other webpack.config.js options to vite.config.js
• uninstall webpack/Babel-related packages
• verify that vite build + vite serve builds and serves the site locally
• verify that the Vite-built site runs on GitHub Pages

Resources/Instructions

• https://vitejs.dev/

hot reloading demo

⌘S is shown in the lower left corner of my screen on save; you can see that changes to AcknowledgeModal.jsx are reflected in the browser in less than a second, without triggering a reload of the entire page

Screen.Recording.2024-06-20.at.8.06.02.PM.mov

[ryanfchase]

Assembling some notes on initial review of this ticket. ETA on notes: within the hour

[ryanfchase]

@aqandrew @Skydodle I'd like this ticket to move forward as a demo for the team. The deliverable will be a branch that members can check out and run locally themselves

Questions / Follow up on Action Items

• In what ways does Vite perform better than Webpack
  • you mentioned easier to set up tests
  • if overall build times / HMR times are better, perhaps a side-by-side comparison (either video, or timed metrics)
• verify that the Vite-built site runs on GitHub Pages
  • this should be the 1st step moving forward to ensure we don't hit a dead end
  • consider creating a fork and getting a GitHub Pages site running as proof of concept

Splitting up work on this ticket

• I'd say we should split up action items on this ticket
  • all action items related to just getting the demo and proof of concept can stay
  • everything related to docs / instructions for the team will go in follow up ticket(s)
• we can have this ticket and all follow up tickets belong to the testing epic: Epic: Testing and Code Coverage #1768

Action Items for Ticket Author @aqandrew

If you're ok with the plan I've proposed...

• modify the ticket's action items as outlined above
• create tickets for the action items that are slated to come after we've demo'd this migration to the team
  • Labels will be draft, Role: Frontend, Size: Missing, Feature: Code Health
  • Add to 311 Data Project Board (it will automatically go to New Issue Approval)
  • Milestone: X - Technical Debt

Action for PM

Similar to above, we'll do the following once we've agreed on the plan:

• Add this ticket and all follow-up ticket(s) to the Testing and Code Coverage epic: Epic: Testing and Code Coverage #1768

[ryanfchase]

Follow up on above comment

I've looked into Webpack's HMR capabilities, it seems like our webpack dev server behaves more like hot reloading rather than HMR.

If we look at our dev server configurations, we are using ..., { devServer: { ..., mode: hot } }, which technically should enable HMR according to Webpack's docs.

I also had a look at a different plugin, React Hot Loader, but it may take some more time before I understand how to get HMR working as intended.

if overall build times / HMR times are better, perhaps a side-by-side comparison (either video, or timed metrics)

Seeing as you got HMR working so quickly with Vite, I can consider this question answered 😄

[aqandrew]

I did also see that our webpack.dev.js appears to have HMR enabled:

311-data/webpack.dev.js

Line 13 in 0d08087

hot: true,

But my local dev server does not behave like HMR.

Timed metrics

Here is a video showing current reload times with webpack. The entire page must be refreshed, which triggers a request for data every time a JS module is changed. I.e., whenever a JS/JSX file is saved.

I've measured the time in this video between hitting Cmd+S and seeing the updated text at 7.88 seconds, 7.81 seconds, and 7.91 seconds. Let's say the time it takes to see changes reflected in the browser is the median value, 7.88 seconds.

Screen.Recording.2024-08-14.at.4.59.39.PM.trimmed.720p.mov

Comparing this to the video in the original comment showing Vite: the slowest refresh occurs between updating "buddy" to "pal". I measured this at 0.58 seconds, 0.58 seconds, and 0.51 seconds. Let's also say that the time it takes to see changes reflected in the browser is the median value, 0.58 seconds. It's important to note that with HMR, app state is preserved because the page does not have to refresh.

By this rough benchmark, we can consider Vite's HMR time to be 7.88 / 0.58 = 13.59 times faster than webpack's refresh time.

[ryanfchase]

Hi @aqandrew,

Please leave a comment with the following items:

• updated ETA
• progress from the last week
• availability for communications during the week

Thanks!

Edit: I moved this to in-progress since it seems you are actively researching / gathering metrics. If you're not currently working on it, you can move it back to Prioritized Backlog with a comment.

[aqandrew]

(My bad, I accidentally moved this to the Icebox--meant to move the testing ticket instead.)

• updated ETA: 9/5/24
• progress from last week: None since the timed metrics comment above. My next step is to confirm that the Vite-built site runs on GitHub Pages. Afterward I'll create a ticket(s) for writing new docs/instructions.
• availability: 9am-5pm

[aqandrew]

I've successfully deployed the Vite-built site on GitHub Pages! 😄 Note the console.log at the bottom of this screenshot:

My fork is at https://github.com/aqandrew/311-data, and hosted at https://aqandrew.github.io/311-data/.

In this process I found that we need to update references to Mapbox environment variable in 2 more places:

1. main.yml
2. repository secrets, in Settings > Secrets and variables > Actions > Secrets > Repository secrets
   

[ryanfchase]

Thank you @aqandrew, I'm very interested to check this out. Please let me know if there is any further work to be done before we can officially move this to "In Review".

[aqandrew]

Next is to redefine meta tags, which are currently handled with HtmlWebpackPlugin. Since we're not using a framework like Next.js, I'll go with react-helmet since it's still a reliable/popular package for managing meta tags (I think?). Will let you know when that's completed.

[aqandrew]

@ryanfchase PR is ready for review! I'll merge latest main into my branch + create the follow-up tickets tomorrow

[ryanfchase]

Moving this to In Review since the PR is now available

[ryanfchase]

Technically there is a dependency, #1824, but I will leave this In Review since only the merging is blocked by this topic.

[ryanfchase]

Moving to Icebox, since the review has been completed, and now the work listed in the dependency must be worked on.

[ryanfchase]

Moved to In Review since I've been re-requested on the PR

[ryanfchase]

@aqandrew question about getting this line while building the project:

The CJS build of Vite's Node API is deprecated. See https://vitejs.dev/guide/troubleshooting.html#vite-cjs-node-api-deprecated for more details.

Have you encountered this warning? Is there something in my build environment that I need to change for this?

Note from Vite docs

Link to doc.

[ryanfchase]

I've successfully deployed the Vite-built site on GitHub Pages! 😄 Note the console.log at the bottom of this screenshot:

(image)

My fork is at https://github.com/aqandrew/311-data, and hosted at https://aqandrew.github.io/311-data/.

In this process I found that we need to update references to Mapbox environment variable in 2 more places:

1. main.yml
2. repository secrets, in Settings > Secrets and variables > Actions > Secrets > Repository secrets

(image)

Updates:

• I've created a ticket based on updating Repository Secrets: PM: Update Repository Secrets to use VITE prefix #1839
• I've also added it to the Epic: Epic: Testing and Code Coverage #1768

[aqandrew]

Have you encountered this [CJS] warning? Is there something in my build environment that I need to change for this?

@ryanfchase Good catch! I've just pushed a commit to import all JS files as ESM instead of CJS: e25aa13

I used the fix that you referenced from the Vite docs.