Starlight Route Data Middleware must not conflict with Astro's middleware (#3018)

Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>
Co-authored-by: delucis <357379+delucis@users.noreply.github.com>

4 files changed, 59 insertions, 1 deletions

diff --git a/.changeset/eight-masks-kick.md b/.changeset/eight-masks-kick.md
new file mode 100644
index 00000000..4766139d
--- /dev/null
+++ b/.changeset/eight-masks-kick.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Adds validation for user config `routeMiddleware` so it does not conflict with [Astro's middleware](https://docs.astro.build/en/guides/middleware/).
diff --git a/docs/src/content/docs/reference/configuration.mdx b/docs/src/content/docs/reference/configuration.mdx
index 53c04e0b..43f8fb64 100644
--- a/docs/src/content/docs/reference/configuration.mdx
+++ b/docs/src/content/docs/reference/configuration.mdx
@@ -603,6 +603,15 @@ For example, this page is titled “Configuration Reference” and this site is
 
 Disables injecting Starlight's default [404 page](https://docs.astro.build/en/basics/astro-pages/#custom-404-error-page). To use a custom `src/pages/404.astro` route in your project, set this option to `true`.
 
+### `routeMiddleware`
+
+**type:** `string | string[]`
+
+Provide paths to route middleware that can modify how Starlight processes your data.
+These file paths must not conflict with [Astro’s middleware](https://docs.astro.build/en/guides/middleware/).
+
+See the [Route Data guide](/guides/route-data/#customizing-route-data) for details about how to create route middleware.
+
 ### `components`
 
 **type:** `Record<string, string>`
diff --git a/packages/starlight/__tests__/basics/config-errors.test.ts b/packages/starlight/__tests__/basics/config-errors.test.ts
index 6b2e9723..a010015f 100644
--- a/packages/starlight/__tests__/basics/config-errors.test.ts
+++ b/packages/starlight/__tests__/basics/config-errors.test.ts
@@ -10,7 +10,7 @@ function parseStarlightConfigWithFriendlyErrors(config: StarlightUserConfig) {
 	);
 }
 
-test('parses valid config successfully', () => {
+test('parses bare minimum valid config successfully', () => {
 	const data = parseStarlightConfigWithFriendlyErrors({ title: '' });
 	expect(data).toMatchInlineSnapshot(`
 		{
@@ -253,3 +253,32 @@ test('errors with sidebar entry that includes `items` and `autogenerate`', () =>
 			**sidebar.0**: Unrecognized key(s) in object: 'autogenerate'"
 	`);
 });
+
+test('parses route middleware config successfully', () => {
+	const data = parseStarlightConfigWithFriendlyErrors({
+		title: '',
+		routeMiddleware: './src/routeData.ts',
+	});
+	expect(data.routeMiddleware).toEqual(['./src/routeData.ts']);
+});
+
+test('errors if a route middleware path will conflict with Astro middleware', () => {
+	expect(() =>
+		parseStarlightConfigWithFriendlyErrors({
+			title: 'Test',
+			routeMiddleware: ['./src/middleware.ts', './src/routeData.ts'],
+		})
+	).toThrowErrorMatchingInlineSnapshot(
+		`
+		"[AstroUserError]:
+			Invalid config passed to starlight integration
+		Hint:
+			The \`"./src/middleware.ts"\` path in your Starlight \`routeMiddleware\` config conflicts with Astro’s middleware locations.
+			
+			You should rename \`./src/middleware.ts\` to something else like \`./src/starlightRouteData.ts\` and update the \`routeMiddleware\` file path to match.
+			
+			- More about Starlight route middleware: https://starlight.astro.build/guides/route-data/#how-to-customize-route-data
+			- More about Astro middleware: https://docs.astro.build/en/guides/middleware/"
+		`
+	);
+});
diff --git a/packages/starlight/utils/user-config.ts b/packages/starlight/utils/user-config.ts
index ad6612db..5fe6ad1d 100644
--- a/packages/starlight/utils/user-config.ts
+++ b/packages/starlight/utils/user-config.ts
@@ -233,6 +233,21 @@ const UserConfigSchema = z.object({
 		.transform((string) => [string])
 		.or(z.string().array())
 		.default([])
+		.superRefine((middlewares, ctx) => {
+			// Regex pattern to match invalid middleware paths: https://regex101.com/r/kQH7xm/2
+			const invalidPathRegex = /^\.?\/src\/middleware(?:\/index)?\.[jt]s$/;
+			const invalidPaths = middlewares.filter((middleware) => invalidPathRegex.test(middleware));
+			for (const invalidPath of invalidPaths) {
+				ctx.addIssue({
+					code: 'custom',
+					message:
+						`The \`"${invalidPath}"\` path in your Starlight \`routeMiddleware\` config conflicts with Astro’s middleware locations.\n\n` +
+						`You should rename \`${invalidPath}\` to something else like \`./src/starlightRouteData.ts\` and update the \`routeMiddleware\` file path to match.\n\n` +
+						'- More about Starlight route middleware: https://starlight.astro.build/guides/route-data/#how-to-customize-route-data\n' +
+						'- More about Astro middleware: https://docs.astro.build/en/guides/middleware/',
+				});
+			}
+		})
 		.describe('Add middleware to process Starlight’s route data for each page.'),
 });