Please critique my workflow for replacing an entire legacy project with a C3TA-scaffolded prototype?
Been prototyping an 80% rewrite of my web app’s frontend scaffolded with Create-T3-App (NextJS 13 with pages, TypeScript, and Tailwind only, no tRPC, Prisma, or Next-Auth) in a separate repo. Significant rewrite with not only newer versions of Next, React, and Cypress, Tailwind as the CSS solution instead of Material-UI, and TypeScript instead of JavaScript, but also React Query, Jotai, and HeadlessUI too. Things have been going very well and I am almost ready to replace the running production frontend as it currently stands with the new frontend.
Main repo in legacy project has three branches: main (main dev branch), staging (auto builds on staging server), and production (auto builds on live production server)
Backend is in separate repo/deployed separately.
Proposed workflow for replacing old frontend with new one: 1. While on the main branch of the web frontend repo, completely empty out its top-level working directory of the entirety of the old frontend, moving the old frontend to a separate archive directory in the process, and copy the new frontend (including node_modules folder) in from the prototype directory. Ensure everything works & all tests pass (about 300 E2E tests I’ve been copying over and adapting) , then push the new frontend up to the main branch. 2. Merge the new frontend into the staging branch and confirm the staging app works. 3. Once it is confirmed that the staging app works, merge the frontend into the production branch at 3:30am on Tuesday morning and pray for no downtime.
Would this complete replacement-in-place workflow be advisable or should I consider a more surgical approach? Thanks in advance!
5 Replies
Old app was scaffolded with create-next-app using Next 10, JS (no TS) and MUI at the end of 2020 if that helps. MUI has been the primary motivation for the rewrite.
I've gone through horrors like this with my Next.js 10, GraphQL, MUI (augh). Thousands of lines, ~200 files
I don't like to release too many changes at once (small team), so:
* from GraphQL to tRPC (easy)
* after lots of testing, I happily ended my GraphQL's life
* removed MUI, replacing it with SCSS modules (I was avoiding Tailwind. I would just go straight from MUI to Tailwind)
* redesigned the components for Tailwind
Sounds like a lot of work; best of luck! I'd say incremental changes are easier on you and your users as well
That probably was a better way to do it, but hindsight is 20/20. I’m gonna rewrite my backend with TS and Drizzle later this year after some time off from codebase rewrites and gonna take a more incremental approach to doing that in the same repo… definitely lesson learned there. But as far as the frontend is concerned, basically right now I have what amounts to an almost-finished fully-functional extensively tested better quality clone of my own app, and once it is actually finished, I want to replace the soon to be legacy production app with the clone and make the clone the actual app, if that makes sense. Right now I’m deciding whether to yeet the legacy codebase out of the repo and drop the new “clone” in in one fell swoop, or replace it in parts (update the deps, then copy the configs, then, copy the TS components over folder by folder, etc), those are the two options I see being viable at this point, the way I’ve done things.
If the current app works fine and it’s more about better maintenance & dev, and you have a flexible timeline, I’d consider the first option.
I spent about 4w on that, but it was the best decision ever, and now we’re shipping much faster and more confidently.
btw feel free to DM me if you encounter any weird issues or have any questions during that!
UPDATE: I ended up doing the first thing, yeeting the legacy codebase from the repo entirely and dropping the successful complete prototype in its place in one fell swoop.
This mostly worked the way it was supposed to (project compiled and deployed mostly as expected and all end-to-end tests passed) except for a couple caveats that I will share for educational purposes:
Hidden files. I used Finder to delete the legacy codebase, which I shouldn’t have done, definitely should have used the Terminal - because some hidden files were left behind from the legacy codebase, most notably .babelrc, .env, and .gitignore, which I noticed as soon as I attempted to compile the new frontend in the main repo and the compiler picked up the .babelrc file from the legacy codebase. Once I deleted the .babelrc file in VSCode and replaced the .env, .env.example, and .gitignore files with the ones from the prototype repo, everything worked and all the tests passed.
When deploying to staging, my deployment platform (DigitalOcean App Platform) still had the old codebase in its build cache and built from the build cache using the old codebase instead of the new one. The solution to this was to force a rebuild/redeployment and check "Clear build cache". After doing this, the build was performed from the new codebase as expected.
Command-P shows tons of deleted files from the old codebase in recently opened which is annoying. The solution to this was to clear the recently opened list out entirely by hand.
That's about it. I had another separate issue with deployment to staging that was completely unrelated to this workflow (a wrong environment variable that caused our CORS protection handler to throw a 403 on attempt to fetch from the backend - that took a bit to figure out), but everything else seems to have gone well so far. The push to production happens in about 15 minutes - wish me luck! Also had to delete and rebuild both my prod and staging branches due to merge issues which was annoying and took down my production site for about a minute but hey that’s why I do deploys to prod at 3am.
That's about it. I had another separate issue with deployment to staging that was completely unrelated to this workflow (a wrong environment variable that caused our CORS protection handler to throw a 403 on attempt to fetch from the backend - that took a bit to figure out), but everything else seems to have gone well so far. The push to production happens in about 15 minutes - wish me luck! Also had to delete and rebuild both my prod and staging branches due to merge issues which was annoying and took down my production site for about a minute but hey that’s why I do deploys to prod at 3am.