[WIP] 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.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 72a9577

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[netlify]

✅ Deploy Preview for astro-starlight ready!

Name	Link
🔨 Latest commit	72a9577
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/6769bf74b5b28300080aa3d5
😎 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	7 KB (0%)
/_astro/*.js	21.19 KB (0%)
/_astro/*.css	13.75 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.md	Source added, will be tracked.
en	reference/overrides.md	Source changed, localizations will be marked as outdated.
en	reference/route-data.md	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]

Context from today’s work: fixed type checks by moving around some code.

Basically the issue was that this PR exposes the StarlightRouteData type ambiently in App.Locals, but that type was colocated with some stuff that imported some of our non-public virtual:* modules. The refactor creates a dedicated utils/routing/types.ts file which avoids imports from our modules using virtual modules. Naming may not be perfect yet. For example, this also moves a few sidebar-related types up to that type file, but it does at least ensure we aren’t forced to expose more public type for the virtual:* modules.

[trueberryless]

I'm also very excited about this PR!

Just to keep track of what has been achieved already and what needs to be done after reading the latest changes:

• We* have a nice and clear name with some namespacing (Personally, I really agree with @lorenzolewis and @delucis)

• Astro.locals.starlightRoute is guarenteed not null because @delucis moved 404 to route data as well. This means we don't need a getter which throws an error like @HiDeoo suggested.

• <StarlightPage> needs to support middleware (solved by running user middleware when setting the route data, now locals.ts and the <StarlightPage> component use the attachRouteDataAndRunMiddleware method)

  This change also adds another new dependency: klona, which makes deep clones easy and fast.

• Discuss proper naming for the type file because it now includes some sidebar-related stuff

Please correct me if any bullet point is wrong or misleading in any way, I'll correct and keep the list up to date if you want.

*We: I don't see myself included, props to @delucis,@lorenzolewis and @HiDeoo