Migration
Migrating from Gulp to Astro
Notes from moving the legacy frontend workflow to Astro.
01
Migrating a legacy WordPress theme to a modern Astro architecture while preserving editorial workflows, SEO and long-term maintainability.
- Client
- pro(G
- Year
- 2023
- Role
- Frontend Developer
- Status
- Completed
Summary
The project started as an opportunity to explore a modern frontend framework while keeping an existing production website alive.
Rather than redesigning the website, the objective was to rebuild its technical foundation and create a frontend that would be easier to evolve over time.
Context
The previous frontend relied on a legacy Gulp workflow tightly coupled to WordPress.
Over time, technical debt increased and maintaining the frontend became more difficult.
Performance often depended on additional WordPress plugins, while I wanted to reduce that dependency and move towards a cleaner, more maintainable architecture.
Challenges
Migrating a legacy Gulp frontend to Astro while learning a completely new framework.
Designing a preview system that allowed editors to preview unpublished content despite using a static frontend.
Rethinking form handling by moving away from WordPress plugins towards API-based services.
Technical Decisions
Choosing Astro
Rather than choosing Next.js or Nuxt, I selected Astro because its philosophy aligned with my own approach to frontend development.
Shipping as little JavaScript as possible by default, excellent static generation and an architecture focused on performance made it the right choice for this project.
Preview Architecture
Because Astro generates static pages, the traditional WordPress preview could not be used.
I designed a dedicated preview workflow based on two deployments:
- Production (Static)
- Preview (SSR)
Using separate Vercel deployments and environment variables allowed editors to preview unpublished content while keeping production fully static.
Workflow
- 01
Build the new Astro foundation.
Reuse the existing styles while reconnecting the frontend to WordPress using WPGraphQL.
- 02
Design a custom preview architecture.
Implement separate Production and Preview environments running on Vercel with dedicated rendering strategies.
Technology Stack
- Astro
- TypeScript
- Tailwind CSS
- WordPress
- Headless WordPress
- WPGraphQL
- Cloudflare
- Vercel
- GitHub
- Cursor
Results
- Significantly faster frontend performance.
- Much smaller dependency on WordPress plugins.
- Cleaner and more maintainable architecture.
- Improved deployment workflow.
- Better security by fully separating the frontend from the CMS.
- Production remains available even if the back-office becomes unavailable.
Notebook
Preview
Building a custom preview architecture
Notes on the separate static Production and SSR Preview deployments.
Content layer
Connecting Astro with WPGraphQL
Notes on reconnecting the frontend to WordPress through WPGraphQL.
Architecture
Reducing WordPress dependencies
Notes on moving frontend responsibilities from plugins to API-based services.
Gallery
