Docusaurus to Astro migration
How Yarn improved website performance and DX with an Astro migration
Yarn serves millions of JavaScript developers worldwide. We migrated their site from Docusaurus to Astro, for free, as a contribution to the open-source community, and delivered a Lighthouse score of 99 in under 2 months.
Background
Yarn is a critical tool in the JavaScript ecosystem. Their website is not just documentation; it's a vital resource where developers discover packages, learn about new features, and evaluate whether Yarn is right for their workflow.
Challenge
Outdated codebase making it difficult and time-consuming to ship updates
Website performance limitations that couldn't handle traffic spikes from new version launches
Poor user experience with confusing package page URLs and missing modern UI elements
High maintenance burden diverting engineering resources from core product development
Solution
We rebuilt the Yarn website on Astro from the ground up: zero JavaScript by default, redesigned package pages, clean URL architecture, and a codebase the team can ship from without a deployment ceremony. Done in under 2 months, a full month ahead of schedule.
Results
Lighthouse score improved from 85 to 99
Faster development velocity, enabling rapid feature shipping
Cleaner and maintainable codebase, reducing engineering overhead
Instant package search results even under peak traffic
Lucky Media proved to be exactly the partner we needed. Initially brought on to tackle technical debt, they quickly became an integral part of our team. Their ability to independently manage complex refactoring work was impressive, and their responsive, collaborative approach made them a pleasure to work with.
Nate Irwin
Chief Product Officer @ Trailhead Labs
Let’s chat
Talk to our founders. Let's figure out what's actually slowing you down.
Challenges
The Yarn website wasn't broken. It was aging. Built on Docusaurus, it had served the community well, but the team knew Astro could deliver meaningfully better performance, a cleaner developer experience, and a codebase easier to maintain long-term. They reached out to us to make it happen.
Slow development workflow slowing down innovation
The Docusaurus-based site required significant developer effort for even minor updates. Build times were slow, and it was difficult to make changes.
Performance limitations under heavy traffic
With a major new version launch on the horizon, Yarn knew its website traffic would surge. For a tool that champions speed and efficiency, a slow website undermined its brand promise and created a poor first impression for new users exploring the platform.
Poor user experience driving friction
Developers demand intuitive, efficient experiences. The old site's complex URL structure and lack of modern interface elements made finding package information unnecessarily difficult.
Engineering resources stretched thin
The Yarn development team's engineering resources were being diverted from innovation to basic site upkeep, slowing overall project progress and preventing the team from being as responsive to community needs as they wanted to be.
Our solution
We delivered a solution focused on getting Yarn to market faster with new features and improvements, so they could start seeing results sooner!
Modernizing the tech stack
We immediately rebuilt the entire website from the ground up using Astro, a next-generation web framework built for speed and developer experience. This wasn't just a lift-and-shift migration; it was a strategic re-platforming designed to eliminate friction from the development workflow.
Why this matters: With Astro, we gave the Yarn team a modern, intuitive development experience. Faster builds, simpler component architecture, and a more streamlined codebase meant that the team could now make changes and see results almost instantly. This directly translates to faster iteration cycles and the ability to ship features with confidence.
Optimized for peak traffic and scale
We used Astro's innovative island architecture to create a site that ships zero JavaScript by default, resulting in exceptional performance. The Lighthouse score improved from 85 to 99, reflecting a dramatic leap in speed, accessibility, and adherence to web best practices. We also completely redesigned the package pages, implementing clean, intuitive, and SEO-friendly URLs and introducing UI elements like loaders to provide instant visual feedback.
Why this matters: Even under peak traffic from major version launches, the package search provides instant results, delivering the responsive experience developers expect.
Cleaner architecture for easier maintenance
The new Astro site is built with a clean, well-organized codebase that eliminates technical debt. We established clear conventions and best practices that make the code easy to navigate and modify. The Yarn team can now make updates and deploy changes with minimal friction, enabling them to maintain a rapid release cadence without being slowed down by maintenance overhead.
Why this matters: Every hour a core engineering team spends on website maintenance is an hour not spent on the product. The new architecture gives that time back, cleanly, permanently, without requiring a specialist to make routine updates.
Let’s chat
We partner with a limited number of brands each quarter to ensure senior-level attention on every project.
The results
The transformation delivered immediate outcomes that directly supported Yarn's business objectives:
Lighthouse score improved from 85 to 99: The new Astro site achieved a near-perfect Lighthouse score, reflecting exceptional performance, accessibility, and adherence to web best practices.
Dramatically faster development velocity: The streamlined development workflow and faster build times enabled the Yarn team to ship updates and new features significantly more quickly.
Cleaner, more maintainable codebase: The Astro migration eliminated technical debt and created a codebase that is intuitive and easy to work with.
Instant package search results: Even under peak traffic from the new version launch, the package search provides instant results, delivering the responsive experience developers expect from Yarn.
99
Lighthouse Performance
100
Lighthouse Accessibility
100
Lighthouse Best Practices
Why it worked
This project worked because we approached it as contributors, not contractors. There was no invoice, no scope negotiation, no change order process. We built what we believed Yarn deserved, to the standard we hold ourselves to, because we wanted the JavaScript community to have it.
The result is a site that reflects what modern open-source infrastructure can look like when it's built without compromise.
Let’s chat
We partner with a limited number of brands each quarter to ensure senior-level attention on every project.
More projects like this
AI application using Laravel and OpenAI
Tech startup saves 960 hours with AI-powered automation
Enterprise Statamic website redesign and development
How data.world achieved 99% faster launches and reclaimed $120k in dev budget