Just wanted to share this story of how we completed our Meteor 3.0 migration at my company medbeauty and how more than a year’s worth of effort is coming to an end with a PR of 439 file changes about to be merged 
Mission Briefing: The Launch Preparation
A little background on the application: it was started in 2014. In my humble opinion, it’s one of the last OG Meteor fortresses as it still utilizes Blaze & Cordova. Full-stack reactivity all the way thanks to collection-helpers. It’s about as OG as you can get.
Liftoff: Initial Trajectory Calculations
The team at medbeauty had already dipped their toes in the 3.0 waters as their migration efforts began in 2023 while I joined them late January 2024. They had migrated lots of bits to async. Even @DanielDornhardt had created a magnificent babel-plugin (which isn’t getting the credit it deserves, by the way) to help keep your Blaze code looking nice while migrating it to async.
Since I had already been involved in the Meteor community, I had been getting notifications in my email with the PRs that were popping up here and there, but didn’t see anything materialize. The core team was hammering away at the core packages, but no love was being shown to Atmosphere packages. After all, a framework is only as good as its surrounding ecosystem—no wonder people were ditching Blaze for React!
I was already skeptical of such an endeavor and didn’t even know if it was feasible. So I started with what I know best: Collection2!
The Launch Sequence: Igniting Collection2
I believe Collection2 is one of those very few packages that act as a cornerstone for the entire Meteor framework. If these packages could be made async-friendly, then the rest would surely follow.
A little side trivia: I never anticipated nor vowed to undertake maintaining Collection2. Back when MCP was just getting started, I created an issue suggesting including the package in the roster due to its importance and the fact that Eric/Aldeed had already moved beyond Meteor. Once the package was moved, I was surprised that StorytellerCZ granted me maintainer access. In hindsight, it was a great decision 
Back to Collection2, work had already started thanks to @Klablink—big shoutout to him as he helped with many packages. I started a PR building on his work and went from there. Bit by bit, I began to understand the changes made and even tried to improve it and cut down on the code changes. This was also the first time in my life where I had released a beta version of Meteor packages (I didn’t know if it was even possible, but hey, we keep on learning).
I kept modifying code & releasing betas, then modifying the package in our application to see if anything would break. Also, Andrei/alisnic came to the rescue. With 2400 unit tests and 821 e2e test cases, surely I didn’t break anything, right?
After a couple of hiccups and many commits, we made it! 4.0.0 was released, affirming the possibility of not only migrating Meteor packages—but in my own eyes—Meteor and Meteor projects as a whole.
Entering Orbit: Community Navigation Challenges
This experience had not only proven the possibility but also revealed the amount of work that awaited us. It highlighted a problem with the coordination of the community because I had seen people not only replicating work but also migrating silently or forking packages entirely! Which could bring an end to this unborn endeavor entirely!
That’s why after brief discussions with Daniel, we came up with the idea to document the packages that needed to be migrated and their current status. This eventually led to the birth of this forum article.
The forum post helped to showcase who was working on what and gave a sense of how things were moving. While I had hoped for more widespread community participation to distribute the workload, the reality was that the effort largely fell to a dedicated group of familiar faces along with a few new contributors. When I shared my thoughts with @alimgafar about wanting more community involvement, he offered a perspective that resonated with me: “that’s how open source™ works” – a small group of passionate contributors often carries the weight of major transitions.
Needless to say, medbeauty & Daniel were both gracious with their time and monetary support. At one point, Daniel even instructed me to take a pause and create PRs for the packages that we had migrated so others could benefit.
Gravitational Anomalies: Deployment Mysteries
As we migrated more and more packages and made significant improvements to our codebase, we became increasingly confident in our ability to increase the version number.
One of the most intriguing things that stood out to me during this phase was that we ran into troubles when we tried building and deploying our Meteor application. The problem had already been reported by @zodern, and surprisingly, we were the third to comment on it!
By that time, I had read countless articles here on the forums about how people had migrated to the lush green 3.0 lands, yet I was left puzzled. If so many teams had successfully made the journey, I wondered why more weren’t encountering this deployment issue. I began to question whether there was a difference between production-grade applications with paying customers versus smaller projects with less complex requirements. The contrast between reported experiences and our own challenges made me curious about what we might be missing.
Course Corrections: Navigation Adjustments
Migrating packages was no easy task. At times, we had to make course corrections and prioritize getting things working instead of getting things right.
I had to make adjustments and make the best of the current situation, which is why I opted to still use node-sass in fourseven:scss instead of switching to leonardoventurini:scss. I had recommended forking and modifying a core package just to make things work.
But this experience didn’t come easily. I had burned weeks on end trying to perfect the packages we’re using. I had to freeze a version of collection-hooks that’s compatible with our code. I commented out pieces of code that utilized autoValue, which still is in the works. And I think that’s the moral of the story I want to drive home: it takes time, there’s no perfect flight path, and you have to make some navigational adjustments.
Thankfully, many commits later, our application is stable and deployed to production, but there’s still remaining work for us as we’re still facing problems with Cordova. We’re currently considering our options of soliciting outside help, so maybe there will be a part 2?
Mission Data: Exploration Statistics
Did you like my storytelling talents? Call me StorytellerEG — because clearly the pyramids make for better storytelling backdrops than Prague Castle!
Now time for some fun mission statistics for those interested:
A picture is worth 1000 words:
- 250 commits (tens of them were trying to re-run the CI actually)
- 439 changed files (200 forked packages?)
- 2 Conversations (I’m a man of few words)
By the way, we had started and closed multiple PRs in the hopes of merging 3.0, so this is probably the 3rd clone with plenty of merged/squashed commits with multiple mini-PRs already merged in, so the amount of code we changed is larger than what’s mentioned in this image.
Mission Control’s Transmission: Guidance for Future Explorers
Since I grew a single grey hair during this migration, this warrants me transmitting wisdom to all you young space cadets out there on how to migrate your applications. So ditch your flight manuals and come listen to how seasoned astronauts do it:
-
Test Your Life Support Systems: Time and time again, I’ve been proven that if you were to boil down all of the best practices of software development, it just comes down to having tests. If you don’t have a robust test suite with plenty of coverage, then you might want to start investing in it immediately. Otherwise, suck to be you, sorry
-
Don’t Jump to Warp Speed Immediately: Don’t kick off your application by pumping it to 3.0 like I did. I thought, “Hey, I’d just increase the version number and go from there fixing errors bit by bit and getting it working.” WRONG!
Again, I learned this the hard way. I tried and failed, or better yet, didn’t even get to try because as I attempted to run
meteor update --release 3.x, it crashed with the following error:MINISAT-out: Cannot enlarge memory arrays. Either (1) compile with -s TOTAL_MEMORY=X with X higher than the current value 67108864, (2) compile with ALLOW_MEMORY_GROWTH which adjusts the size at runtime but prevents some optimizations, or (3) set Module.TOTAL_MEMORY before the program runs. MINISAT-err: Cannot enlarge memory arrays. Either (1) compile with -s TOTAL_MEMORY=X with X higher than the current value 67108864, (2) compile with ALLOW_MEMORY_GROWTH which adjusts the size at runtime but prevents some optimizations, or (3) set Module.TOTAL_MEMORY before the program runs. abort() at Error at jsStackTrace (packages/logic-solver.js:21:18626) at stackTrace (packages/logic-solver.js:21:18809) at abort (packages/logic-solver.js:51:28956) at enlargeMemory (packages/logic-solver.js:21:19142) at Function.dynamicAlloc [as alloc] (packages/logic-solver.js:21:7927) at _sbrk (packages/logic-solver.js:21:58803) at Sd (packages/logic-solver.js:25:98389) at Ud (packages/logic-solver.js:25:109800)This is what pushed me into dissecting this into small pieces and starting this whole 3.0 libraries migration thread.
-
Install Your Warning System: Enable the
WARN_WHEN_USING_OLD_APIenv variable. It’s a little env variable that got added during 2.12 but didn’t get much attention. Enabling it should be your first pre-flight check. -
Gradual Engine Upgrades: Once you’ve enabled it, slowly start migrating all of your old DB calls to async.
-
Replace Components Methodically: As you’re doing the previous step, you might need to start swapping out the old Meteor packages with the new ones. Act accordingly and, most importantly, patiently. You don’t want to introduce too many changes at once; that’s how you crash your spacecraft. Don’t ask how I know.
-
Multiple Small Launches Beat One Big One: Introduce changes in small, separate PRs as much as you can. We migrated all our packages and DB calls before launching into the final frontier—err, 3.0, I mean.
-
Share Your Flight Log: Share your experience and stay in touch. It helped me immensely that I was cross-referencing many ideas with the community and reporting any issues back to mission control. In a way, this article is part of this migration journey so we can collectively learn and elevate each other.
Mission Accomplished: Return to Earth
After more than a year of work, our Meteor 3.0 migration is complete and running in production. This achievement wouldn’t have been possible without the support of the open source community.
Special thanks to @Klablink, @alisnic, @bratelefant, @vparpoil, @leonardoventurini, @dr.dimitru, and @paulishca who contributed critical components to this ecosystem-wide effort. I apologize if I forgot any names.
If you’d like help migrating to 3.0 or generally would like to connect and chat about your own space mission, I’ve set up a cal account.
