Migrating a Website from MODX to Next.js with the Help of AI Tools

Introduction

Migrating a website from MODX to Next.js might sound daunting at first, but it became a necessity driven by both technical and security considerations. MODX, while powerful in its time, relies on a PHP-based stack with complex templates, snippets, and plugins that can be challenging to maintain. More critically, MODX has faced numerous security vulnerabilities over the years, with multiple successful hacking incidents reported across the web. A simple search for "MODX hacked" reveals countless security breaches, making it clear that staying on this platform posed significant risks to data integrity and website security.

Next.js, in contrast, offers a modern, React-based approach with server-side rendering, API routes, and a highly flexible component system. Beyond the technical advantages, Next.js provides a more secure foundation with regular security updates, a robust ecosystem, and modern security practices built into the framework. Perhaps most importantly, Next.js can generate static HTML files that are essentially unhackable—with no server-side processing or database vulnerabilities to exploit, static sites eliminate most common attack vectors entirely.

In this project, AI tools became essential partners in the migration process. Tools like Gemini CLI, Claude Code, and OpenAI’s Codex helped accelerate development, understand legacy code, and generate boilerplate—turning what could have been weeks of manual work into a smoother, more predictable workflow.

Migration Goals and Objectives

This migration project encompassed several key objectives that required careful planning and execution:

1. Bootstrap 3 to Bootstrap 5 Upgrade – Modernize the UI framework to leverage the latest features, improved responsive design, and enhanced component library.

2. MODX to Next.js Platform Migration – Transition from the PHP-based MODX content management system to a React-based Next.js framework for better performance, maintainability, and developer experience.

3. Content Recovery and Page Recreation – Reconstruct missing pages by analyzing and extracting data from the original website's database dump, ensuring no content was lost during the transition.

4. Contact Form Modernization – Replace the legacy send_mail functionality that became obsolete after moving away from cPanel hosting, implementing a new contact form solution compatible with the modern infrastructure.

AI Tools for the Job (Rescue!)

Overall, To tackle this complex migration, I leveraged three powerful AI development tools: Claude Code, Gemini CLI, and OpenAI Codex. Rather than relying on a single solution, I strategically tested each tool with similar and different tasks to evaluate their strengths and identify the best approach for each aspect of the migration. This comparative approach proved invaluable — each tool excelled in different areas.

First Things First: Original Website Template Obtainment

Assuming we still can have the website up and running, so we can build a template from the home page which will provide a common structure (menu, header, footer, etc) for the rest of the pages.

Option 1

Use any web scraping tool to get the HTML of the home page. For example, using curl:

Copy curl -o homepage.html https://www.example.com

If you need to scrape more than just the HTML files but also the assets (CSS, JS, images), you might consider using a more comprehensive tool. There are many open-source web scrapers available online, such as crawl4ai, crawlee, scrapy, etc. I even developed my own web scraper tool, which is available on GitHub: tyolab/tyo-crawler.

Option 2

Just use Claude Code to scrape the website for you. For example, you can provide the following prompt:

I need you to scrape the homepage of https://www.example.com and and save all the assets, and save them in @template

Converting HTML Template to a Next.js project

Once you have the HTML template, the next step is to convert it into a Next.js project. This involves creating a new Next.js application, setting up the necessary pages and components.

Previously I already built a html-to-nextjs converting tool, which is available on GitHub: tyolab/UnoWeb, it can create a boilerplate next.js project from an HTML template and in a way how I want to have my website managed.

Copy node convert.js \
--from /new_web/template \
--to /new_web/code \
--engine nextjs \
--strip_layout false \
--replace_partial false \
--page home \
--overwrite true \
--section banner,main,contact,services,advantage,blog,footer \
index.html

The section argument is used to specify the sections of the page that should be converted into separate components. This allows for better organization and reusability of code. You should adjust the section names based on the actual sections present in your HTML template. The last argument is the HTML file name, that is existing in the from directory that you want to convert from.

You may also use Claude Code to convert the HTML template to a Next.js project. For example, you can provide the following prompt:

I need you to convert the HTML template in @new_web/template to a Next.js project and save it in @new_web/code. Please create separate components for each section of the page, such as header, footer, main content, etc.

Prompt Engineering

Once we have the basic Next.js project set up, the next step is to migrate the content from the MODX site to the new Next.js site. This involves extracting data from the MODX database dump and converting it into a format that can be used in Next.js components.

I constructed various types of prompts based on the migration objectives, experimenting with different levels of specificity and context to optimize results.

Sample Prompts

To effectively migrate content from MODX to Next.js, I developed a series of prompts tailored to specific tasks. These prompts were designed to guide the AI tools in generating the necessary code and components.

Upgrade Bootstrap 3 to Bootstrap 5

"I need you to upgrade the Bootstrap 3 code in @new_web/code/components/ and @new_web/code/pages/ to Bootstrap 5. Please ensure that all components, classes, and utilities are updated to their Bootstrap 5 equivalents. Save the updated files back in the same directory."

Recreating the Missing Pages

One example of the detailed prompts I used demonstrates the complexity of coordinating multiple data sources:

"I need you to create Next.js pages using the navigation structure from @new_web/code/settings/home/main.json. Generate the corresponding pages in @new_web/code/pages/ with content inferred from the database dump @data/business_site.sql. Apply the styling patterns established in @new_web/code/components/home/ as the foundation for the new components. Since this is a MODX to Next.js conversion, please break down each page into logical sections and save them as separate components in @new_web/code/components/[page]/ directories accordingly."

This type of structured prompt allowed the AI tools to understand the relationship between legacy data, new architecture, and design patterns, enabling them to generate more accurate and contextually appropriate code. By providing clear file paths and explicit instructions about data sources, the tools could maintain consistency across the migration while preserving the original site's content and navigation structure.

Deployment and Troubleshooting

Actually, these AI tools not just can help you to re-construct the website, but also can help you deploy and troubleshoot it.

To deploy the new Next.js website and the WordPress-powered blog, I created a virtual machine (VM) on Google Cloud Platform (GCP) and utilized Docker containers for efficient hosting and management of both applications.

I need you to re-import the data dump file to the remote VM with this file @data/bussiness_blog_site.sql, because this is the latest dump

For troubleshooting, I found that Claude Code was particularly effective. For instance, when I needed to search through the database dump for specific content, I used a prompt like:

could you search all database dump to see which one contains a blog post with title "How to connect power cables to the MSI PRO Z790-P Series Motherboard"

AI tools significantly streamline DevOps tasks by automating command retrieval and log analysis. Instead of manually searching through command history or troubleshooting errors, you can simply prompt these tools to handle the process, saving time and reducing effort.

Tool Comparison

Different phases of the migration benefited from different AI copilots. After iterating on dozens of prompts, a clear pattern emerged in how each tool contributed value.

Claude Code

Claude Code consistently behaved like a senior engineer who lives inside a shell session. It excelled at unpacking legacy PHP snippets, interpreting obscure MODX template tags, and then translating the logic into modern React. When I needed to refactor large swaths of code, Claude handled the chore of reorganizing files, generating Bash one-liners, and confirming the results.

Gemini CLI

Gemini felt like pairing with a patient data scientist who uses a lot of Python. It was slower to respond, but it did thoughtful analysis whenever I fed it database exports or CSVs extracted from the old CMS. Gemini was the go-to when I needed schema summaries, content audits, or regex-heavy transformations before handing the cleaned data to Next.js components.

However, Gemini CLI came with notable drawbacks. The initial configuration was more complex than expected, requiring careful setup of API credentials and environment variables. More critically, quota limits and rate limits frequently interrupted workflow—long analysis sessions would hit API caps, forcing breaks in productivity. Combined with its already slow response times, these limitations meant Gemini required patience and careful task planning to use effectively.

OpenAI Codex

Codex shined in rapid prototyping. Whenever I needed the first draft of a Next.js page, a React hook, or a Tailwind configuration tweak, Codex produced clean, idiomatic code in seconds. Its best use was as an idea amplifier—generate the scaffolding with Codex, then refine with Claude or Gemini depending on the task.

That said, Codex didn't particularly stand out compared to the other tools. Like Gemini, it had a strong preference for Python when solving problems, even when JavaScript or shell scripts might have been more appropriate for the context. While competent, it lacked the specialized depth that made Claude or Gemini indispensable for specific tasks.

Putting It Together

The most productive workflow emerged by chaining the tools: Gemini to inventory data, Claude to plan and refactor, and Codex to sprint through implementation details. Treating them as specialized teammates, rather than interchangeable assistants, kept the migration moving quickly without sacrificing accuracy.

While I found Claude Code to be the most versatile and dependable tool for this migration, the combined strengths of all three AI assistants were essential to completing the project efficiently within a tight schedule.

Results and Outcomes

The migration from MODX to Next.js was a resounding success, achieving all primary objectives while significantly enhancing the website's performance, security, and maintainability. Key outcomes included:

• Modernized UI: Upgraded from Bootstrap 3 to Bootstrap 5, resulting in a more responsive and visually appealing design that leverages the latest web standards.
• Improved Performance: The Next.js framework, with its server-side rendering and static generation capabilities, led to faster load times and a smoother user experience.
• Enhanced Security: By moving away from MODX and adopting a static site generation approach, the website is now far less vulnerable to common web attacks, significantly reducing the risk of future security breaches.
• Content Integrity: Successfully recovered and recreated all missing pages using data extracted from the original database dump, ensuring that no content was lost during the migration.
• Modern Contact Form: Implemented a new contact form solution that is compatible with the current hosting environment, replacing the obsolete send_mail functionality.
• Efficient Development Process: Leveraged AI tools to streamline the migration process, reducing the time and effort required to translate legacy code into modern React components.

Overall, the migration not only revitalized the website but also positioned it for future growth and adaptability in an ever-evolving digital landscape.