Moving to Astro
jenxi.com Vision alchemist crafting strategic innovation & AI adoption. Bridging startups to China’s ecosystem advantage. Building a cyberbrain. Registered pharmacist × Brand strategist × Storyteller
Moving a website to a new platform is like updating your smartphone—you don’t want to lose your data and settings, but you’re eager to access new capabilities that make life easier.
Migrating from a decades-old WordPress site isn’t just about transferring content—it’s about rethinking how everything works together, especially when moving from a CMS to a web framework like Astro. The goal was to keep all the features I’ve accumulated over the years that have shaped my digital home while adopting new workflows and capabilities.
My journey with Astro began as a simple experiment with Cursor AI in AI-assisted web development, but it evolved into something more significant: a thoughtful migration that refined and enhanced my digital home of over two decades.
The AI Catalyst
Cursor is a code editor by Anysphere that brings the power of AI to your web development and text-editing workflow. It’s probably the biggest thing in the developer industry this year.
The story of an 8-year-old building her AI chatbot with Cursor in 45 minutes finally pushed me to explore AI-assisted web development. I’d been tracking Cursor AI’s progress, intrigued by its potential to transform how we write code. As someone who has been building websites since the Geocities era, I’ve seen many tools promise revolution but Cursor delivers.
My experience with Cursor AI felt like having a knowledgeable coding partner. It caught errors quickly and offered suggestions I might have missed—much more helpful than digging through Stack Overflow posts. More importantly, it helped me understand why certain approaches worked better than others.
Cursor comes with the popular LLM models, including Claude’s 3.5 sonnet or ChatGPT-4o, GPT-4o mini. I use Claude most of the time and fall back to GPT-4o when doing simpler tasks.
I approached this with my usual autodidactic approach to learning. Rather than diving into tutorials or documentation, I learn best when working towards a concrete goal. In this case, it was switching one of my WordPress sites to a web framework.
My personal website is a rather sacred space, so the logical choices was to work on a local experiment with WuxiaSociety. I was already building a new version of it with NuxtJS. This helped me get up to speed with Tailwind CSS.
But things quickly got out of control—in a good way. I was learning so much from Cursor AI that I felt comfortable enough to take on a more ambitious project.
From curiosity to migration
The transition wasn’t dramatic—it was methodical. My initial goal was modest: experiment with Cursor AI while learning a new framework. Having previously tested both NuxtJS and NextJS, I had leaned towards NuxtJS for its more HTML-centric approach over a JavaScript-centric one.
However, conversations with Claude AI helped me question my assumptions and evaluate my actual needs. Yes, I chat with AI a lot. It’s more like brainstorming and thinking augmented by AI’s vast knowledge.
This reflection led me back to Astro. More on this later. Its approach to selective JavaScript—generating static content by default while allowing interactive elements where beneficial—aligned perfectly with my goals. I wasn’t looking to rebuild from scratch; I wanted to refine what worked while adding subtle enhancements that were challenging to implement in WordPress without extensive customisation.
A tale of multiple sites
Over the years, my website had evolved a main WordPress site into a distributed system of WordPress installations, each serving a specific purpose.
The Chinese blog helped me understand translation contexts for my contributions to WordPress Polyglots. The photo portfolio lived separately due to specific theme requirements, and I didn’t want to bog down my main blog with photo gallery plugins.
The journal section ran on ComicPress that required a standalone WordPress installation due to how it displayed posts, though that changed later on but I ran it separately because moving it was a hassle, and why change something if it isn’t broken? Which ironically is something I ignored this time.
This fragmentation had made sense historically, but times change. With Astro, I saw an opportunity to consolidate these pieces while preserving their individual character. The migration would allow me to:
- Serve static pages instead of dynamic content
- Implement smooth view transitions
- Create a pure CSS photo gallery
- Rebuild the chapter hierarchy for journal entries
- Maintain a bilingual publishing workflow
The technical journey
What started as an experiment yielded surprising results. Within five days, I had a functional design that captured the essence of my existing site while incorporating subtle improvements.
Cursor AI wasn’t just generating code—it was helping me understand why certain approaches worked better than others. One trick I learnt was to share more of my rationale, thought process, and desired outcome to help it better understand my intent and context.
Framework decisions
The decision to use Astro wasn’t immediate, even though I’ve been tracking it since it was released in 2022. Reading about Koos Looijesteijn moving to Astro recently actually convinced me not to consider it, hence my experiment with NuxtJS.
My experience with NuxtJS had been positive, and I was growing comfortable with its patterns. However, through conversations with Claude AI, I began wondering whether I needed such a comprehensive framework for what was essentially a content-focused site.
I like how Claude questioned my stance and pushed me to rethink my considerations and shake my preconceived notion to dismiss Astro as a viable option.
Claude walked me through the process and showed me how Astro’s approach resonated with my needs. It functions as a static site generator, but allows selectively addition of JavaScript functionality. This meant I could maintain fast load times without sacrificing interactivity where it mattered, but still drop in JavaScript where needed.
In fact, Astro allows you to use any framework. This means you can migrate from NuxtJS, NextJS, or SvelteKit while sticking to Vue.js, React, or Svelte as the JavaScript framework.
The built-in Markdown support was particularly appealing, as it simplified the content migration process from WordPress.
Migration and improvements
Converting WordPress content to Markdown proved straightforward with AI assistance. Claude created a conversion script to process my WordPress XML export. It generated each post as a Markdown file while preserving my post metadata as YAML frontmatter. So all I had to do was to drop the files into Astro’s content folder to display them with Astro.
More importantly, Cursor helped me develop a more logical tagging system for my content. I won’t bore you with the details of the process. In short, it involved finding common themes in my articles and then using terms that would perform better for SEO.
The process is easier than you think. Since I can get Cursor to scan my whole codebase, it basically could digest all the information in my articles to help me list down the topics I’ve written over the years. 🤯
The WordPress migration process goes beyond just moving the content. The photo gallery and the journal’s comic navigation were features that needed some work.
Photo slider
The photo gallery was an interesting challenge. I had to rely on using plugins when implementing image sliders on WordPress, but with Astro I could easily create a pure CSS solution that offered better performance and more control over the presentation.
Sure, I could have done the same with a WordPress plugin but that would require more work to implement, which is precisely why I haven’t done so all these years.
Journal
I was able to rebuild the journal section’s chapter hierarchy to sort and manage the journal entries. After support for ComicPress ended, I switched to using the default WordPress posts to serve the images. This meant managing them as posts and grouping them with categories and tags. While it works, it’s still a roundabout way to do so.
Not that it’s any different from ComicPress. Since the plugin was developed by non-developers with a specific need to display comics, and their hard work helped many comics springboard to success, the implementation always felt a little crude and it did not age well.
With Astro, the posts are just images and Markdown files in folder. Working with Astro also gave me some ideas for new features, though I’ve temporarily hidden some until I expand the content volume.
Platform considerations
The deployment process brought its own learning opportunities. Testing across Cloudflare Pages, Vercel, and Netlify revealed interesting differences in how these platforms handle static site generation. I’ve used GitHub Pages for BakingPixel for years and wanted to see what the competition can do, so I skipped it.
I ran into build issues on cloud with NuxtJS, and also when with Astro. Rather than banging my head trying to figure out the problem, I went with the pragmatic solution: build locally and upload the rendered files to Cloudflare Pages.
Vercel deployed the static files without any hiccups, but the dashboard was more confusing than Cloudflare’s. Netlify had problems serving even the static files. I didn’t see the need to debug the Netlify issue at this point.
Lessons learned
What struck me most about this migration wasn’t the speed of development—though completing the initial design in five days was remarkable for me. It was how AI enhanced my understanding of web development concepts.
Being able to question Cursor AI about its suggestions led to deeper insights into framework architecture and modern web development practices.
Having Cursor AI as a development partner meant I could explore alternatives and understand trade-offs in real-time, strengthening my grasp of modern web development practices.
I’ve learnt that it is crucial to question the AI—not to disagree or doubt it—but to understand why it is doing things in a certain way. This context helps a lot in grasping the direction or solution it decides to go with, and you can then make a better decision whether it is doing the right thing. Or if you need to guide it down a different path.
That’s my biggest takeaway: using AI to validate or challenge my assumptions and deepen my understanding. And this applies beyond just coding and web development.
Looking forward
The migration to Astro serves as a testament to how AI tools are transforming development workflows. It’s not about replacing human developers but augmenting our capabilities. AI helped me work faster while making more informed decisions about architecture and features.
Some key insights from this experience:
- AI tools are most effective when used for learning, not just code generation
- The ability to question and understand AI suggestions is crucial
- Small, incremental improvements can add up to significant enhancements
- Sometimes the best features are the ones you decide not to implement
As I continue to refine and improve the site, these lessons will guide future development decisions. The goal isn’t to chase every new technology or feature, but to thoughtfully enhance the user experience while maintaining the site’s core purpose: sharing ideas and connecting with readers.