Add support for component overrides

[TheOtterlord]

What kind of changes does this PR include?

• Changes to Starlight code

Description

• Closes Ability to customise Starlight’s components #415
• What does this PR change? Adds a user config option to provide components overriding built-in Starlight components

Todo

• Documentation
• Test/Fix importing internal Starlight components (@astrojs/starlight/internal?)
• Support custom layouts? (possibly out of scope/not something we want)

[changeset-bot]

⚠️ No Changeset found

Latest commit: 0878164

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	0878164
🔍 Latest deploy log	https://app.netlify.com/sites/astro-starlight/deploys/64ff077d13949a0008c1ce4d
😎 Deploy Preview	https://deploy-preview-638--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.

[lorenzolewis]

(omg omg omg the excitement is real ❗)

[delucis]

Hey @TheOtterlord! Wanted to thank you for kicking this off. We’ll probably have to go a slightly different direction to support all the features we want though. Overriding loading like this, similar to Vite’s resolve.alias config option I think could cause issues when:

• A user wants to import one of our built-in components and actually get the original implementation (e.g. to wrap it/extend it with some extra code)

• Supporting our concept of “layout slots” (not sure yet what we should call these), but basically pre-defined places in the layout that are usually empty where a user can slide things into without impacting default components. For that to work with an override approach, we’d need a separate empty component for each “slot”.

Pretty sure we also don’t want people to end up importing all these various component-specific prop types and have varies access to the route context depending on which component they’re in.

I’ve been doing some work on the https://github.com/withastro/starlight/tree/dx-326/component-customization branch to refactor our internal codebase and standardise all components to receive a single consistent props object. There are a couple of exceptions to this in our recursive list components for the sidebar and table of contents, but on the whole it works well.

Currently prototyping an override system locally and I think the best solution is to use a virtual module.

Basic flow:

1. Users configure component overrides in the Starlight config, e.g. { components: { Footer: './my-footer.astro' } }. For any components they don’t define, we use a default value, e.g. @astrojs/starlight/components/Footer.astro.

2. In Starlight’s Vite plugin we inject a virtual module that re-exports each of these, e.g.

   export { default as Footer } from '@astrojs/starlight/components/Footer.astro';
   // etc.

   (switching the module name for whatever a user provided instead if overriden)

3. In Starlight component code, instead of importing components directly we import from this virtual module.

This means that a user can still get the original implementation by importing it directly, while we can override components as needed.

[TheOtterlord]

Yep, I like this. I had a similar plan for forwarding components, but I like the prop standardisation too. I'll close this PR, and the efforts can continue in https://github.com/withastro/starlight/tree/dx-326/component-customization

[delucis]

Thanks @TheOtterlord! Sorry to not have got this feedback to you earlier. But still super helpful to see this prototyped. I didn’t have the load() hook on my radar as an option, so this helped make sure I saw that and could evaluate it amongst our options.