VitePress vs Starlight for Vue and Astro Teams

VitePress and Starlight are the two lightest documentation frameworks in common use, and they are often shortlisted together: both are fast, both look good out of the box, both have local search. The difference that matters most is not on their feature lists. VitePress is a Vue application that pre-renders pages and then hydrates them for client-side navigation; Starlight is an Astro site that renders HTML and ships JavaScript only for the few interactive parts. That one architectural choice drives the differences in page weight, customisation and who finds each comfortable to work with.

This comparison builds the same 500-page documentation set — Markdown with code blocks, tables, admonitions, about 300 images and two languages — in VitePress 1.5 and Starlight 0.30, and measures build time, page weight, Core Web Vitals, search and the effort to customise each. It sits under Docs Frameworks: Docusaurus, Starlight and VitePress, which also covers Docusaurus.

Method

• Content: 500 pages ported from an existing product docs site, English plus a 120-page German translation.
• Configuration: each framework's defaults plus sidebar, logo, edit links and local search. No custom components beyond admonitions and tabs, which both support natively.
• Builds: GitHub Actions 4-core runner, hyperfine with five runs after one warm-up.
• Page metrics: Lighthouse 12 mobile on five representative pages, median of five runs each, served from Cloudflare.

Build Time and Output

Starlight's longer build is mostly image processing: it converts and resizes every image in content through astro:assets. Disabling that brought it to 22 seconds. VitePress serves images as they are unless you add a pipeline yourself.

Page Weight and Core Web Vitals

The two frameworks make opposite trade-offs. VitePress ships a Vue runtime and router so that moving between pages is a client-side transition — near-instant once loaded. Starlight ships almost nothing, so the first page is lighter and faster, and later navigations are full page loads, made quicker with Astro's prefetch. For docs where most readers land from search and read one or two pages, Starlight's model wins on the metrics that are measured in the field; for readers who browse many pages in a session, VitePress feels faster after the first page.

Search

Both ship local search with no external service. VitePress uses MiniSearch with one index per locale, loaded when the search box opens: 290 KB compressed for the English site. Starlight uses Pagefind, which splits its index into fragments and loads only those a query needs, so a query costs about 45 KB regardless of site size. At 500 pages both are fine. Past a few thousand pages, Pagefind's fragmenting scales better without extra work, while VitePress's single index needs the tuning described in Adding Local Search to a VitePress Site.

Internationalisation

Starlight's i18n is more complete. It ships translated UI strings for over 30 languages, falls back to the default language for untranslated pages with a notice, and generates per-locale sidebars from the folder structure. VitePress supports locales through separate locales config blocks, each with its own nav, sidebar and UI labels that you translate yourself; untranslated pages are simply missing. For the 120-page German translation, Starlight needed 8 lines of config. VitePress needed 140 lines of duplicated nav, sidebar and label config, plus a script to generate redirect stubs for missing translations. Teams planning more than one or two languages should weigh this heavily; Internationalizing Starlight Docs covers the Starlight side in depth.

Customisation

VitePress customisation is Vue all the way down, which a Vue team will find effortless and anyone else will find a context switch. Starlight's overrides are Astro components, and because it is an Astro integration, the marketing site, blog and docs can live in one Astro project — a real advantage for teams that would otherwise run two frameworks.

Maintenance and Ecosystem

Both are maintained by the teams behind their parent tools (the Vue core team and the Astro team) and release frequently. VitePress reached 1.0 in early 2024 and has kept its configuration stable since. Starlight was still below 1.0 during this comparison and made small breaking changes in several minor releases; each needed under an hour of work on the test site, but they were more frequent than VitePress's. Starlight's plugin ecosystem is larger and growing faster — OpenAPI docs, blog, versioning, link validation — while VitePress relies more on writing Vue yourself.

Migration Effort Between Them

Because the content is Markdown in both, moving between them is mostly configuration. Porting the 500-page test set from VitePress to Starlight took about a day: frontmatter needed title and description (VitePress pages had used the first heading as the title), VitePress's ::: tip containers became Starlight's :::tip asides with a regex, <CodeGroup> blocks became Starlight <Tabs>, and the sidebar config was rewritten as folder-based autogeneration with a few manual groups. The reverse direction is similar in size. The work that does not port is custom components: Vue components in a VitePress theme can move to Starlight through the Vue integration, but Starlight overrides written as Astro components would have to be rewritten in Vue for VitePress.

For a team undecided between them, that asymmetry is a reason to keep custom components to a minimum in the first months. The content will move either way; the components are the switching cost.

Verdict

• Choose VitePress if the team writes Vue, the docs are for a Vue or Vite ecosystem library, readers browse many pages per visit, and the site has one or two languages.
• Choose Starlight if the team uses Astro or React, page weight and Core Web Vitals matter, the docs need several languages, or the docs should live in the same project as a marketing site.

Pitfalls

• Comparing on defaults only. Starlight's image processing doubles its build time; VitePress's lack of it may cost page weight on image-heavy docs.
• Judging navigation speed on the first page. Measure a multi-page session if your readers browse.
• Underestimating i18n effort in VitePress. UI strings and fallbacks are on you.
• Assuming Vue components rule out Starlight. They work through the Vue integration.

Conclusion

On the same 500 pages, VitePress built faster and navigates faster after the first page; Starlight shipped a quarter of the JavaScript, scored better on first-load metrics and needed far less configuration for a second language. The choice follows the team's framework and the readers' behaviour more than any single benchmark.

FAQ

Is VitePress or Starlight faster to build?

On the 500-page test set in this guide, VitePress built in 19 seconds and Starlight in 31 seconds on the same runner. Both are fast enough that build time rarely decides between them below a few thousand pages; Starlight's extra time goes mostly into image processing and its richer Markdown pipeline.

Which ships less JavaScript to readers?

Starlight. Its pages ship about 18 KB of JavaScript compressed, mostly for search and the theme toggle, because Astro renders everything else to HTML. VitePress pages ship about 72 KB, because VitePress hydrates pages as a Vue single-page application for client-side navigation.

Can I use Vue components in Starlight or Astro components in VitePress?

Starlight can use Vue components through Astro's Vue integration, rendered to HTML or hydrated as islands. VitePress can only use Vue components. A Vue team with an existing component library can use it in either, but an Astro or React team will find Starlight a more natural fit.

Which one handles translations better?

Starlight has more complete internationalisation built in, including translated UI strings for over 30 languages, per-locale sidebars and fallback content for untranslated pages. VitePress supports locales with separate configs per language but leaves UI string translation and fallbacks to you.

Related

• Parent: Docs Frameworks: Docusaurus, Starlight and VitePress — all three frameworks compared.
• Docusaurus vs Starlight for Product Documentation — the React-side comparison.
• Comparing Docs Framework Build Times — build time at larger scales.
• Adding Local Search to a VitePress Site — tuning VitePress's search index.
• Customizing Starlight Without Forking the Theme — Starlight's override model in practice.