Starlight Route Data Middleware must not conflict with Astro's middleware

[trueberryless]

What is your idea?

As @delucis noticed in Discord, the Starlight middleware must or may not conflict with the Astro middleware. In other words, the behaviour of the middleware is I think unpredictable and not investigated at the moment, if you create your Starlight middleware in src/middleware.ts . I would say, that we recommend against creating your custom route data inside a file that gets processed by Astro itself.

There are a few point to consider here:

• First, I'm not an expert myself, but maybe we need to know more about what's really happening if your middleware gets processed by Astro and Starlight. Like: Does it really conflict and mess up some things? Could future releases break it? What's the worst that could happen if you just name your Starlight middleware file wrong...
• Then I think we are able to answer some of those questions:
  • Shall we enforce that the Starlight middleware is not allowed to be located at src/middleware.js|ts or src/middleware/index.js|ts? Eg throw a "Starlight middleware must not be located in {filePath}" error if the user tries to?
  • Or shall we just document that the middlewares must not conflict (PR example: Starlight Route Data Middleware must not conflict with Astro's middleware #3018)?

Why is this important?

I don't know how severe the impacts are when you create your Starlight middleware under src/middleware.ts because it gets processed by Astro, but as Chris said, we must probably recommend against doing so.

How does your idea relate to existing docs content?

No response

Participation

• I am willing to submit a pull request for this feature.

[delucis]

I think it would make sense to enforce it with a nice error in code so people clearly understand what to do when they hit it.

Should be quite easy to do in our schema here:

starlight/packages/starlight/utils/user-config.ts

Lines 231 to 236 in 2f8cd17

	routeMiddleware: z
	.string()
	.transform((string) => [string])
	.or(z.string().array())
	.default([])
	.describe('Add middleware to process Starlight’s route data for each page.'),

Use .refine() to check if any middleware paths are src/middleware.{js|ts} or src/middleware/index.{js|ts}. The only theoretically tricky bit is that in theory people can set a custom srcDir which this schema is unaware of, but I think it maybe be OK to only handle the common case here perhaps?

[trueberryless]

I too agree we should enforce it, but having this inconsistency with the srcDir feels wrong...

[delucis]

It’s not ideal, but I think it’s probably an acceptable trade-off. It lets us validate simply, with the same error approach as other configuration errors and will cover 99.99% of people doing this I would expect. (Only 0.9% of Starlight projects set srcDir according to our stats and an even smaller percentage of those will create a conflicting middleware file I guess).

[trueberryless]

Perfect!

I didn't know you had some nice stats on that. Pretty useful info rn 🎉

Nice, then I'll undraft the PR and make it ready for review...

[HiDeoo]

The validation was released in Starlight 0.32.6 🎉