PRD for Migrating to Meteor 3 using AI tools

help
1

Just checking if anybody has tried AI tool to migrate to meteor 3.0 - atleast to do the grunt work.

Is it possible? I am trying. Created one using Gemini. I have to test.
I was however successful doing some of it, struggled more with packages.

PRD: Migration of [Your App Name] from Meteor 2 to Meteor 3

Field Value
Document Title PRD: [Your App Name] Meteor 3 Migration
Author [Your Name/Team]
Stakeholders Product, Engineering, QA, DevOps
Status Draft
Version 1.4
Date 2025-08-10

1. Introduction

This document outlines the requirements, scope, and plan for migrating our application, [Your App Name], from its current Meteor 2.x architecture to the new Meteor 3.0 framework. Meteor 3 represents a fundamental modernization of the platform. Key changes include the removal of Fibers in favor of async/await, the adoption of Vite and standard ES Modules (which affects file load order and global variables), and closer alignment with the Node.js ecosystem.

This migration is a critical technical initiative to ensure the long-term health, performance, and maintainability of our application.

2. Goals and Objectives

The primary goal is to successfully run [Your App Name] on a stable Meteor 3.0 release in production.

The key objectives are:

  • Modernization: Align our codebase with modern JavaScript standards (async/await) and eliminate reliance on the legacy Fiber-based concurrency model.
  • Performance: Leverage the performance improvements of Meteor 3, modern Node.js, and the Vite build system to enhance application speed and developer experience.
  • Future-Proofing: Position our application to take advantage of future Meteor updates and the broader npm ecosystem without the limitations of the previous architecture.
  • Security & Stability: Ensure the application runs on fully supported versions of Node.js and underlying dependencies.
  • Maintainability: Improve the developer experience by using tools and patterns that are standard in the wider web development community.

3. Scope

In-Scope

  • Upgrading the Meteor framework version to 3.0.
  • Upgrading the Blaze UI library to version 3.0 and refactoring all templates, helpers, and event handlers to ensure compatibility.
  • Auditing all Atmosphere and npm packages. This includes upgrading compatible packages and handling incompatible ones by either replacement or direct patching.
  • Forking critical, incompatible Atmosphere packages into the local /packages directory and refactoring them to be Meteor 3.0 compatible.
  • Creating a local “compatibility package” from the existing client, lib, config, and common directories. This is to manage file load order and preserve critical global variables, overcoming the new ES Module scope limitations.
  • Refactoring all server-side code to replace Fiber-based, synchronous-style code with standard async/await patterns.
  • Migrating our build process to be compatible with Vite.
  • Updating our deployment scripts, CI/CD pipelines, and local development environments for Meteor 3.
  • Comprehensive testing to ensure functional parity.

Out-of-Scope

  • New Features: No new user-facing features will be developed as part of this migration.
  • Major UI/UX Redesign: The user interface will not be redesigned. The goal is functional and visual parity.
  • Complete Business Logic Refactoring: Business logic will only be refactored where necessary to accommodate the async/await changes. A ground-up rewrite of features is not in scope.

4. Risks and Mitigation

Risk Likelihood Impact Mitigation Strategy
Loss of Implicit Globals Certain High Mitigation: A “compatibility package” will be created from the lib, common, client, and config directories. This package will use the package.js API to explicitly control file load order and export necessary variables to the global object, ensuring they remain accessible throughout the application and minimizing the need for an immediate, large-scale refactor.
Package Incompatibility High High Audit & Strategize: Conduct a full audit of all dependencies. For incompatible packages, decide to either Replace with a modern alternative or Fork & Patch. The “Fork & Patch” strategy involves downloading the package source into the local /packages directory to be manually updated.
Breaking Code Changes (Server) Certain High Static Analysis: Use linters to identify areas needing async/await refactoring. Dedicated Branch: Perform all work on a separate meteor-3-migration branch. Code Review: Enforce rigorous code reviews focused on async correctness.
Breaking UI changes in Blaze 3.0 Medium Medium Review: Carefully study the Blaze 3.0 changelog. Targeted QA: Perform thorough testing on all UI components, focusing on reactivity and event handling. Refactor: Allocate time to refactor helpers and event maps to work with async data sources correctly.
Timeline Slippage High Medium Phased Approach: Break the migration into clear, manageable phases. Prioritization: Focus on the most critical paths first. Clear Ownership: Assign clear owners to each part of the migration.

5. Migration Plan

This migration will be executed in distinct phases.

Phase 0: Preparation & Analysis (Sprint 0)

  1. Dependency Audit: Create a spreadsheet of all Atmosphere and npm packages. For each incompatible package, document the chosen strategy: Replace (identify a compatible alternative) or Fork & Patch (plan to download the source to the local /packages folder for manual updating).
  2. Establish Baseline:
    • Ensure the existing test suite has maximum coverage and is fully passing.
    • Capture performance benchmarks for key user flows.
  3. Setup Environment: Create the meteor-3-migration git branch. Set up a test environment that can be used for deploying and testing the migrated application.
  4. Review Documentation: The entire engineering team should review the official Meteor 3 and Blaze 3.0 Migration Guides.

Phase 1: Core Technical Migration

  1. Update Meteor Version & Dependencies: Update the .meteor/release file and all compatible npm/Atmosphere packages.
  2. Fork Incompatible Packages: For packages designated for the “Fork & Patch” strategy, download their source code into the /packages directory. Remove the original Atmosphere dependency declaration.
  3. Create Compatibility Package:
    • Create a new local package (e.g., app-legacy) in the /packages directory.
    • Move the contents of the root lib/, common/, config/, and client/ directories into the app-legacy/ package.
    • Create a package.js file for app-legacy.
    • In package.js, use api.addFiles() to define the exact load order of the moved files, mimicking the old Meteor load order rules (e.g., files in a lib subdirectory are loaded first).
    • Identify all variables that were previously global (e.g., Collections, Utils) and explicitly export them using api.export('VariableName', ['client', 'server']).
  4. Patch Forked Packages: Refactor the code of the other local packages within the /packages directory to make them Meteor 3.0 compatible.
  5. Address Breaking Changes (Application Code):
    • Server-Side (The “Great Refactor”): Systematically refactor all application server-side code (now primarily in server/) to use async/await.
    • Client-Side (Blaze 3.0): Refactor application Blaze helpers, event handlers, and lifecycle hooks (now within the app-legacy package) for compatibility with Blaze 3.0.
  6. Build System: Configure vite.config.js and ensure all assets and imports work correctly.

Phase 2: Testing & Quality Assurance

  1. Automated Testing: Run the full suite of unit and integration tests. Fix any failures. Add new tests for refactored logic where necessary.
  2. Manual E2E Testing: QA and Product teams perform a full regression test of the application on a staging server. Special attention must be paid to UI rendering, component reactivity, and event handling to validate the Blaze 3.0 upgrade and to test functionality provided by the newly patched local packages.
  3. Performance Testing: Deploy the migrated app to a staging environment and re-run the performance benchmarks. Compare results against the Phase 0 baseline. Address any significant regressions.
  4. User Acceptance Testing (UAT): A limited group of internal users tests the application to catch any final issues.

Phase 3: Deployment & Post-Launch

  1. Deployment Plan: Document a detailed production deployment plan. A blue-green deployment is recommended to allow for instant rollback.
  2. Production Release: Execute the deployment plan.
  3. Monitoring: Closely monitor application performance, error logs, and server metrics for at least 48 hours post-launch.
  4. Rollback Plan: Have a clear, documented plan to revert to the Meteor 2 version of the application if critical issues are discovered.
2 Likes
2

@perumalkuk

Previously, Visual Studio Code Insiders did not work for this, it stopped to rate limits. I have also tried some other AIs for upgrades.

But 2 days ago I tried Cursor, that was able to use IDE agent mode and convert Meteor 2 Jade WeKan to Meteor 3 React WeKan. But then it got stuck at “Uncaught RangeError: Maximum call stack size exceeded” that is now same error at Meteor 3, that I also had at Meteor 2. Cursor also started repeating itself at text output it made. Anyway, Cursor is very very good, it is the first AI that was able to upgrade from Meteor 2 to Meteor 3.

I also mentined about WeKan upgrades at webpage: Upgrade WeKan ® — Open-Source kanban

3

I am also using Cursor. I used cursor and followed step by step migration recommended on Meteor site. It was slow and lot of refactoring of code. The biggest challenge was with packages and its dependencies, for most of them had to create local copies. Still not completed with the migration, meteor is coming up but there is an issue with useraccount routes.

However I wanted to see if I should redo again from scratch. I was trying to create a comprehensive prd that can be fed to the AI agent for it do the changes in the right way

4

I had this error few times, it happened when I forgot calling “fetchAsync()” before using functions to work with array.

5

@perumalkuk

I used cursor and followed step by step migration recommended on Meteor site. It was slow and lot of refactoring of code.

I did run Cursor at macOS at my M1 Air. Cursor was not slow for me. I did not use any any migration guide. I just wrote one step a time, like “convert all Jade templates to React”, what dependency to replace, “upgrade forked packages at packages directory from fibers to async await”, etc.

You can look at my Meteor 3 WeKan repo about what dependencies I’m using at package.json , .meteor/packages , .meteor/versions . Those work with Meteor 3.

You can also look at what dependencies Meteor 3 RocketChat uses.

6

Sure, but I don’t know how to fix it and where, both at Meteor 2 and Meteor 3.

7

I did not mean cursor was slow, I meant doing step by step is slow.

I followed similar to yours. I think sometimes cursor does refactoring of code and this means lot of testing is required.
I have to see if conversion of useraccounts and Blaze3 was ok, However Meteor3 comes with a login page but it does not go further

8

@perumalkuk

For login, there is example here:

I have fork here with some changes:

I did talk about it at this Meteor JS Community Podcast:

Since WeKan version 7.93, Meteor 2 WeKan Snap version uses qemu-user to run MongoDB at Intel/AMD CPUs that do not support AVX, like my Windows Vista era Core 2 Duo laptop that has 8 GB RAM:

Similarly it would be possible to run MongoDB at arm64 CPUs like RasPi4 that do not have some CPU features MongoDB requires.

It is also possible to replace MongoDB with FerretDB/PostgreSQL:

9

I think you have errors log on the server.