At some point, my Next.js portfolio stopped making sense. The site worked, but I felt it carried more complexity than I needed: unused APIs, configurations that got in the way, and overhead that didn’t justify a static site. That’s when I decided to migrate to Astro — not as a simple framework switch, but as an engineering exercise with AI support.
Why Astro over Next.js?
The first reason was performance. Astro ships HTML by default and only adds JavaScript when it’s truly necessary. In practice, this means faster sites with fewer SEO headaches.
The second reason was simplicity. For a portfolio and technical blog, I didn’t need the entire machinery of Next.js. I wanted something straightforward, easy to maintain, without unnecessary layers.
And finally, flexibility: Astro lets me reuse React components seamlessly. That gave me the freedom to port what made sense and rethink the rest.
How I organized the migration
Before opening the editor and rushing into code, I decided to structure my process.
This is where AI came in: I used Cursor, an editor with an integrated copilot, to keep both projects (the old one in Next.js and the new one in Astro) side by side.
I also set up internal documentation with:
- a simple style guide,
- standard prompts,
- and a place to record architectural decisions.
The idea was clear: don’t rely on chat history, but make the AI work inside the project. I asked it to always think step by step, justify decisions, and ask me before moving forward. This made a huge difference: instead of just following along, I became an active part of the process.
The challenges along the way
Not everything was “copy and paste.” Each step forced me to rethink the architecture:
-
Interactivity: in Next.js, a lot depended on React context. In Astro, I had to separate what was truly interactive and turn it into islands. It was a great chance to simplify and cut down dependencies.
-
Global state: keeping
Context APIfor a portfolio was overkill. I switched to Nanostores, which are lighter and more straightforward. The result: cleaner code, no unnecessary wrappers. -
Content: one of my favorite parts was configuring content collections in Astro. Now my posts are structured with schema validation for required fields. I gained consistency and a solid base to grow the blog in the future.
-
SEO and i18n: I also took the opportunity to review meta tags, dynamic titles, and set up the foundation for having an English version later without duplicating effort.
The role of AI
Cursor didn’t handle the migration on its own, but it acted as a pair programming partner.
It suggested architecture alternatives, helped refactor components, and sped up small adjustments.
Of course, it didn’t always get it right — sometimes it overcomplicated things or brought irrelevant solutions. But with clear rules and documentation inside the repo, it became a useful partner instead of a crutch.
Early results
I haven’t collected formal metrics yet, but the feeling is clear:
- The build runs much faster
- The site is lighter
- And I now have a ready-to-grow article system
These improvements already make the migration worth it, even before the official numbers.
Lessons learned
- Document before coding saves time — for both humans and AI.
- Migration is not just porting code: it’s about evaluating if the architecture still makes sense today.
- Astro shines when content and performance are top priority.
- AI speeds things up, but decisions remain in the developer’s hands.
What I took from this migration from Next.js to Astro
This migration wasn’t the biggest challenge of my career, but it was a great opportunity to align my portfolio with what I really needed: a lightweight site, easy to maintain, and ready to evolve.
And more importantly, it was a practical exercise in using AI consciously during development.
🚀 Now my portfolio not only reflects my projects, but also the way I like to work.
And you? Have you ever gone through a framework migration? What mattered most in your decision?