Move route data to Astro.locals

[delucis]

Description

• Early draft PR exploring moving Starlight’s route data object to Astro.locals — currently this is passed down via Astro.props to all our templating components.

• There are some tricky nuances here for sure.

• For example, middleware runs for all routes on a site, which can include non Starlight pages. For these we can’t generate route data. For now I’ve reflected this in the types for locals and asserted Astro.locals.routeData! in the components. There’s not really a sensible way to guard that without duplicating a null check in every component, but also it feels like route data should be defined in all cases where Starlight’s <Page> is rendered.

• The <StarlightPage> component poses some challenges. Right now you pass some props and it generates route data. I’ve hacked this in by assigning that generated data to locals inside the component for now, but this does mean you can’t transform data for pages created this way with additional middleware. Not sure there’s any way to solve this?

  • One way might be to have a dedicated system of “route data middleware” implemented at the Starlight level instead of using generic Astro middleware, e.g.

    starlight({
      routeMiddleware: './some-file.ts',
    })

    We could bundle those in a virtual module and have both Starlight’s locals.ts and <StarlightPage> use them or something:

    context.locals.routeData = await useRouteData(context);
    for (const fn of routeMiddleware) {
      context.locals.routeData = fn(context.locals.routeData);
    }

• The current branch rips out the prop drilling entirely. That means any overrides that rely on Astro.props will break. Could it be worth doing something to ease migration? Deprecate props but keep them around? Throw an error something like we did for labels? Something to think about.

• There’s probably a tidier way to do some of the code — just did the quick and easy thing for now. (For example, Content is currently typed as optional in the route data object to make it easy to throw it in where I needed it, without checking all the places that type is used. But could probably tidy that up to have a dedicated separate type.)

• Can also discuss naming here. So far it’s Astro.locals.routeData, but there’s probably an argument for something a bit more descriptive like Astro.locals.starlightRoute or even just Astro.locals.starlight potentially.

To-do

• Remove demo middleware from docs

[changeset-bot]

🦋 Changeset detected

Latest commit: 1820dec

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@astrojs/starlight	Minor
@astrojs/starlight-docsearch	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	0496d99
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/67b06bfd96f9360009565b95
😎 Deploy Preview	https://deploy-preview-2390--astro-starlight.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 100 (no change from production) Accessibility: 100 (no change from production) Best Practices: 100 (no change from production) SEO: 100 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

size-limit report 📦

Path	Size
/index.html	6.93 KB (0%)
/_astro/*.js	25.76 KB (0%)
/_astro/*.css	13.8 KB (0%)

[lorenzolewis]

Really exciting to see this!

The current branch rips out the prop drilling entirely. That means any overrides that rely on Astro.props will break. Could it be worth doing something to ease migration? Deprecate props but keep them around? Throw an error something like we did for labels? Something to think about.

With the i18n update didn't we have a somewhat breaking change (possibly that's the labels update you're talking about)? I feel like if it's at all possible to keep current behavior around and mark it as depreciated then it would be much more helpful. This change will probably impact A LOT of users who have spent time crafting component overrides.

Can also discuss naming here. So far it’s Astro.locals.routeData, but there’s probably an argument for something a bit more descriptive like Astro.locals.starlightRoute or even just Astro.locals.starlight potentially.

Is there any norm here in Astro-land for 3rd party integrations? This has a potential for name collisions if a user has implemented middleware, correct? If that's the case then I think it would be good to at the very least prefix any locals with starlight.

[HiDeoo]

Sharing a few quick thoughts before I forget them as I've been playing with the idea locally too and we can discuss more in depth later.

For now I’ve reflected this in the types for locals and asserted Astro.locals.routeData! in the components.

As this impacts components and not user components, I've been experimenting with a getter function instead that throws if the route data is not available, which would mean it was called in a non-Starlight route.

The <StarlightPage> component poses some challenges.

Definitely a tricky one indeed, been trying a few things but haven't found something that I'm happy with yet too.

Deprecate props but keep them around? Throw an error something like we did for labels?

As we have seen from the 0.28.0 reports, it's relatively easy to craft explicit errors for Astro.props.* usage in user code altho it gets confusing for users when it's coming from a plugin.

If we compare to labels, in a panel of 15 plugins, only 3 where using Astro.props.labels so the impact was pretty low. This would definitely not be the case for all other props. Still need to think about this one but if we go with the same approach as labels, we should make sure to mention it in the changeset/breaking change that users should make sure their plugins are up to date (which is something I didn't think about for labels).

[delucis]

Spent a bit of time revisiting this PR and feeling quite positive about the idea. Made the following adjustments, which helps it feel better:

1. I pulled 404 route data up into our route data process as well. This means that we can guarantee the locals will always contain Starlight data, even if it is only the 404 route for pages Starlight doesn’t know about. Avoids the need for a getter that throws an error (which I also played with for a bit) and means we really centralise all the data operations in the route data layer.

2. I renamed locals.routeData to locals.starlightRoute. Feels better to namespace it a bit and also feels better when using things like entry.data where the repeat “data” in the path — locals.routeData.entry.data — felt kind of repetitive and vague. starlightRoute expresses things nicely I think.

There’s a type error I’m not 100% sure about — I guess we’re pulling some of our virtual modules into view for type checking that we weren’t previously? Not sure, but haven’t investigate too much. Next up I’d like to tackle the idea of a route data “middleware”/“pipeline” so that users and plugins have a place to plug in and modify stuff.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/overriding-components.mdx	Source changed, localizations will be marked as outdated.
en	guides/route-data.mdx	Source added, will be tracked.
en	guides/sidebar.mdx	Source changed, localizations will be marked as outdated.
hi	guides/overriding-components.md	Localization changed, will be marked as complete.
hi	guides/sidebar.mdx	Localization changed, will be marked as complete.
id	guides/overriding-components.md	Localization changed, will be marked as complete.
id	guides/sidebar.mdx	Localization changed, will be marked as complete.
en	reference/overrides.md	Source changed, localizations will be marked as outdated.
en	reference/plugins.md	Source changed, localizations will be marked as outdated.
en	reference/route-data.mdx	Source added, will be tracked.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[delucis]

OK, I think this should be ready!

Noting I had to make some small link fixes to Hindi and Indonesian docs pages, so this should be merged with a Lunaria tracking directive in the commit message:

@lunaria-ignore:docs/src/content/docs/hi/**.mdx;docs/src/content/docs/id/**.mdx

Paging @yanthomasdev to confirm that will do what I want!

---

Edit: we landed on this directive to be safe:

@lunaria-ignore:docs/src/content/docs/hi/**.mdx;src/content/docs/hi/**.mdx;docs/src/content/docs/id/**.mdx;src/content/docs/id/**.mdx

[HiDeoo]

Amazing work and such a great set of changes. Lots of future improvements to come for everyone thanks to this PR 🤩

[trueberryless]

OMG, you guys have actually done it! I can't put it into words how excited I am! 🎉🍾🎂🎈🎁