Starlight 0.42

Starlight is Astro’s official package for building fast, accessible documentation websites, with all the features you need built in.

Today, we have a riddle for you: how can one Starlight release contain both less JavaScript and more JavaScript? Read on to find out!

Here’s what’s on the agenda:

Less JavaScript with the Popover API
Goodbye TypeScript, hello JavaScript
Performance improvements
Accessibility improvements

To upgrade an existing Starlight site, use the automated @astrojs/upgrade CLI tool. This will update Starlight, Astro, and any other integrations you are using:

npx @astrojs/upgrade

See the Starlight CHANGELOG for migration guidance and full details of breaking changes.

Thanks to the Popover API, Starlight’s mobile menu now works even if a user’s JavaScript fails or is disabled:

Demonstration of the mobile menu in the Starlight docs working even when JavaScript is explicitly disabled in dev tools.

There are more reasons why JavaScript may not work than you might think, so leaning on browser primitives like this makes for faster and more robust websites, while shipping less client-side JS. See the implementation PR for more details.

Goodbye TypeScript, hello JavaScript

A cool quirk of Astro projects is that you can publish TypeScript files to npm and they work when people install them. This is great for quick prototyping — no need to figure out a build step, just publish your source code — and it’s how Starlight has been published since the beginning.

However, distributing TypeScript files comes at a cost. Users who typecheck with tsc can end up type checking your code, because TypeScript will check any imported .ts file it finds, even if it is in node_modules. And they’ll typecheck with their TypeScript configuration, not yours. In some case, type performance in the editor can also suffer. For a large project like Starlight these problems add up.

So Starlight v0.42 comes with 100% more JavaScript! We now compile our source files, ship type definitions instead of TypeScript, and users should see faster type checking. (Don’t worry though, the average Starlight site will still ship 3–13× less JavaScript to end users than comparable tools.)

Performance improvements

We’re always working to improve build times. Recent releases include several incremental improvements:

The latest release of Sätteri enabled us to optimise some of our components and Markdown plugins and reduce Starlight’s dependency count.
Sidebar data processing is now up to 1,400× faster, which will be particularly noticeable in sites with large or deeply nested sidebars.

Accessibility improvements

As of version 0.41.3, the Starlight mobile menu traps focus while open to prevent users tabbing into the page while it is hidden below the menu. This makes the keyboard navigation experience on small or zoomed-in viewports less confusing as required by WCAG Success Criterion 2.4.11 Focus Not Obscured.