7/1/2026 · Atylus
Migrating to Astro and Starlight Without Breaking Design or SEO
A summary of the structural and SEO decisions used while moving a SCSS-heavy Next.js project to Astro and Starlight.
Problem Statement
Changing frameworks without changing the design usually introduces two risks:
- The CSS cascade can break.
- SEO signals can weaken while rebuilding crawlable information architecture.
Strategy Applied
- The global SCSS layer was preserved.
- Existing layout class names were reused.
- Documentation moved to Starlight.
- The blog was modeled with Astro content collections for type safety.
Expected Gains
- Lower client-side JavaScript cost
- Clearer documentation information architecture
- Better static HTML output
- Easier sitemap and search integration
