👾 Using Codex for Monorepo-Scale NextJS Migrations

[flyblackbox]

Using Codex for Monorepo-Scale Migrations (and 3.26 Example)

TL;DR
This thread documents how to use Codex (ChatGPT + GitHub integration) to scan, understand, and refactor our entire legacy React codebase at monorepo scale — and how we’re applying it to user stories like 3.26 Migrate UserPosts Components.

💬 If you’d like to pair on this or join a “Codex Hack Time,” leave a comment below.

---

📌 Example Story: 3.26 Migrate UserPosts Components

• Story: 3.26 Migrate UserPosts Components
• Issue: 3.26 Migrate UserPosts Components #42
• PR: Migrate UserPosts components to TypeScript and Apollo quotevote-monorepo#282

We’re using this story as a concrete test case for a Codex-powered migration workflow.

---

Why This Matters

Most LLM workflows are file-by-file copy/paste.
This discussion shows how to use Codex as a monorepo-scale Migration Assistant that can:

• Scan the entire repo and build an inventory of legacy patterns
• Understand the architecture (legacy src-old/* → new app/ + components/)
• Apply consistent migration rules across dozens of stories
• Open branches + PRs for each story, with automated validation

This is the workflow that makes Codex actually useful for 100+ migration stories, not just one-off refactors.

👋 Pleazd Get Involved

If you want to:

• Pair program screen share live Codex migrations
• Help refining and testing the prompts
• Run this workflow for your own story
• Join a Codex Hack Time session

---

1. Connect Codex to GitHub

In Codex (or ChatGPT with Code Interpreter + GitHub):

1. Go to Settings → Connected Apps
2. Enable GitHub
3. Select the repo and grant:
   • Read access (scan)
   • Read/Write access (branches + PRs)

Once connected, Codex can:

• Traverse directories
• Open and diff files
• Detect legacy patterns (MUI, React Router, fetch, etc.)
• Create branches and commits
• Open PRs for each migration story

---

2. Teach Codex the Repo Structure

First prompt after connection:

Scan the entire repository and produce a directory map of:

• src-old/*
• src-old/components/*
• src-old/pages/*
• src-old/graphql/*
• app/*
• components/*

Identify legacy React patterns, Material UI usage, shared utilities,
GraphQL definitions, and router logic. Summarize architecture.

This gives Codex a working mental model of:

• Where legacy JSX lives
• Where the Next.js App Router expects components
• How GraphQL is structured
• How imports and shared primitives are organized

---

3. Define Migration Rules Once

We give Codex project-level conventions up front:

These are the rules for migrating any legacy React component
to our Next.js / TypeScript architecture:

1. Convert .jsx → .tsx
2. Replace all Material UI imports with shadcn/ui
3. Replace inline styles with Tailwind classes
4. New components live under components/*
5. Use Apollo Client hooks for data fetching
6. Add "use client" only when necessary
7. Use @/ absolute imports
8. Use shared primitives from components/ui/*
9. Match the design/patterns of two “golden” migrated TSX examples

Codex now has a migration grammar that can be applied to every story.

---

4. Repo-Level Scanning Commands

Once rules + structure are known, we run a scanning prompt:

Scan the repo and list every file that:

• imports from @mui/* or material-ui
• uses .jsx
• lives under src-old/components
• contains useState/useEffect (potential "use client")
• uses fetch() instead of Apollo
• uses React Router instead of Next.js conventions

Return a CSV:
file_path | detected issues | recommended migration target

Codex produces a machine-readable inventory of all legacy patterns.
This becomes the canonical migration backlog.

---

5. Automatic Component-by-Component Migration

Automation prompt:

For each file in the scan results:

• Open it from GitHub
• Generate a migrated TSX under components/*
• Apply all migration rules
• Create a branch migration/<component-name>
• Commit the migrated file
• Open a PR "Migration: <component-name>"
• Include a diff summary + checklist

Codex will:

• Open legacy files
• Generate new TSX files
• Push branches
• Open PRs for review

This is real codebase renovation, not just advice.

---

6. Safeguards Before Commit

Guardrails to enforce before Codex pushes:

• Run TypeScript type checks
• Validate imports resolve
• Confirm Apollo queries match schema
• Ensure no shadcn/ui import errors
• Ensure Next.js App Router usage is valid
• Run tests if present
• Block commits on any errors

Codex can be instructed to enforce all of this automatically.

---

7. End-to-End Workflow (Copy/Paste Prompt)

We then provide Codex with a single master “Operating Prompt”:

• Connect to GitHub
• Scan repo + produce directory tree
• Generate a migration inventory for src-old/components/*
• For each file:
  • Convert .jsx → .tsx
  • Replace MUI with shadcn/ui
  • Add Tailwind styling
  • Use Apollo Client
  • Add "use client" only when needed
  • Place result under components/...
  • Commit on branch migration/<name>
  • Open a PR

Validation rules:

• All imports resolve
• No MUI imports remain
• All TypeScript errors fixed before commit
• Components follow project conventions

Codex starts by scanning the repo and waits for human approval before modifying anything.

---

8. Single-Story Mode (e.g., 3.26 UserPosts)

For each story, we:

1. Paste the “Primary Migration Assistant Prompt”
2. Paste a single user story (e.g., 3.26 UserPosts) with:
   • Summary
   • Tasks
   • Expected Behavior
   • Tech Notes
   • Acceptance Criteria
   • Test Instructions

Codex then:

• Identifies all affected files
• Builds a story-specific migration plan
• Migrates components to TSX
• Updates imports + data fetching
• Suggests tests + test pages
• (Optionally) opens a branch + PR

Example story text for 3.26 Migrate UserPosts Components is already included above and in the PR.

---

9. After This: Apply to All 100 Stories

Once this pattern is stable for 3.26, we can:

• Reuse the same operating prompt for each story
• Feed Codex one story at a time
• Let it scan, refactor, and open a PR for that story

This is how we scale migrations across the entire monorepo.

---

👉 Leave a comment below and mention which story (e.g., 3.26, 3.27, etc.) you’d like to help with.

We’ll use this discussion to:

• Iterate on the prompt set
• Share good/bad experiences
• Store links to stories + PRs
• Coordinate Codex-powered refactors across the repo