Make Starlight compatible with server output mode (#1454)

Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>

7 files changed, 34 insertions, 2 deletions

diff --git a/.changeset/cool-days-look.md b/.changeset/cool-days-look.md
new file mode 100644
index 00000000..9480b36c
--- /dev/null
+++ b/.changeset/cool-days-look.md
@@ -0,0 +1,7 @@
+---
+'@astrojs/starlight': minor
+---
+
+Makes Starlight compatible with [on-demand server rendering](https://docs.astro.build/en/guides/server-side-rendering/) (sometimes referred to as server-side rendering or SSR).
+
+Starlight pages are always prerendered, even when using `output: 'server'`.
diff --git a/.changeset/spicy-moose-approve.md b/.changeset/spicy-moose-approve.md
new file mode 100644
index 00000000..aeaefb13
--- /dev/null
+++ b/.changeset/spicy-moose-approve.md
@@ -0,0 +1,11 @@
+---
+'@astrojs/starlight': minor
+---
+
+Enables Astro’s [`experimental.globalRoutePriority`](https://docs.astro.build/en/reference/configuration-reference/#experimentalglobalroutepriority) option and bumps the minimum required Astro version.
+
+⚠️ **BREAKING CHANGE** The minimum supported Astro version is now 4.2.7. Upgrade Astro and Starlight together:
+
+```sh
+npx @astrojs/upgrade
+```
diff --git a/docs/src/content/docs/manual-setup.mdx b/docs/src/content/docs/manual-setup.mdx
index 082325d6..68fb8b0b 100644
--- a/docs/src/content/docs/manual-setup.mdx
+++ b/docs/src/content/docs/manual-setup.mdx
@@ -125,4 +125,7 @@ In the future, we plan to support this use case better to avoid the need for the
 
 ### Use Starlight with SSR
 
-Currently, Starlight does not support [SSR deployment](https://docs.astro.build/en/guides/server-side-rendering/) using Astro’s server adapters. We hope to be able to support this soon.
+You can use Starlight alongside custom on-demand rendered pages in your project by following the [“On-demand Rendering Adapters”](https://docs.astro.build/en/guides/server-side-rendering/) guide in Astro’s docs.
+
+Currently, documentation pages generated by Starlight are always prerendered regardless of your project's output mode. We hope to be able to support on-demand rendering for Starlight pages soon.
+
diff --git a/packages/starlight/404.astro b/packages/starlight/404.astro
index 61358234..556541b9 100644
--- a/packages/starlight/404.astro
+++ b/packages/starlight/404.astro
@@ -7,6 +7,8 @@ import { generateRouteData } from './utils/route-data';
 import type { StarlightDocsEntry } from './utils/routing';
 import { useTranslations } from './utils/translations';
 
+export const prerender = true;
+
 const { lang = 'en', dir = 'ltr' } = config.defaultLocale || {};
 let locale = config.defaultLocale?.locale;
 if (locale === 'root') locale = undefined;
diff --git a/packages/starlight/index.astro b/packages/starlight/index.astro
index 65128ae8..60f90162 100644
--- a/packages/starlight/index.astro
+++ b/packages/starlight/index.astro
@@ -5,6 +5,8 @@ import { paths } from './utils/routing';
 
 import Page from './components/Page.astro';
 
+export const prerender = true;
+
 export async function getStaticPaths() {
 	return paths;
 }
diff --git a/packages/starlight/index.ts b/packages/starlight/index.ts
index 205cc23b..56d72ab4 100644
--- a/packages/starlight/index.ts
+++ b/packages/starlight/index.ts
@@ -43,11 +43,15 @@ export default function StarlightIntegration({
 					injectRoute({
 						pattern: '404',
 						entrypoint: '@astrojs/starlight/404.astro',
+						// Ensure page is pre-rendered even when project is on server output mode
+						prerender: true,
 					});
 				}
 				injectRoute({
 					pattern: '[...slug]',
 					entrypoint: '@astrojs/starlight/index.astro',
+					// Ensure page is pre-rendered even when project is on server output mode
+					prerender: true,
 				});
 				// Add built-in integrations only if they are not already added by the user through the
 				// config or by a plugin.
@@ -78,6 +82,9 @@ export default function StarlightIntegration({
 					scopedStyleStrategy: 'where',
 					// If not already configured, default to prefetching all links on hover.
 					prefetch: config.prefetch ?? { prefetchAll: true },
+					experimental: {
+						globalRoutePriority: true,
+					}
 				});
 			},
 
diff --git a/packages/starlight/package.json b/packages/starlight/package.json
index 103ad8d2..b0aa5c82 100644
--- a/packages/starlight/package.json
+++ b/packages/starlight/package.json
@@ -167,7 +167,7 @@
     "./style/markdown.css": "./style/markdown.css"
   },
   "peerDependencies": {
-    "astro": "^4.0.0"
+    "astro": "^4.2.7"
   },
   "devDependencies": {
     "@astrojs/markdown-remark": "^4.2.1",