Added config option for setting a hostname to be prepended to Server Island URLs

.changeset/sour-taxis-warn.md

@@ -0,0 +1,5 @@
+---
+'astro': minor
+---
+
+Added config option for setting a hostname to be prepended to Server Island URLs. This will allow users to deploy Server Island server-side code seperately from generated static output.

packages/astro/src/core/app/types.ts

@@ -113,7 +113,8 @@ export type SSRManifest = {
 	pageModule?: SinglePageBuiltModule;
 	pageMap?: Map<ComponentPath, ImportComponentInstance>;
 	serverIslandMappings?: () => Promise<ServerIslandMappings> | ServerIslandMappings;
-	key: Promise<CryptoKey>;
+	serverIslandHostname?: AstroConfig['serverIslandHostname'];
+  key: Promise<CryptoKey>;
 	i18n: SSRManifestI18n | undefined;
 	middleware?: () => Promise<AstroMiddlewareInstance> | AstroMiddlewareInstance;
 	logger?: () =>

packages/astro/src/core/build/plugins/plugin-manifest.ts

@@ -365,6 +365,7 @@ async function buildManifest(
 		middlewareMode,
 		site: settings.config.site,
 		base: settings.config.base,
+		serverIslandHostname: settings.config.serverIslandHostname,
 		userAssetsBase: settings.config?.vite?.base,
 		trailingSlash: settings.config.trailingSlash,
 		compressHTML: settings.config.compressHTML,

packages/astro/src/core/config/schemas/base.ts

@@ -65,6 +65,7 @@ export const ASTRO_CONFIG_DEFAULTS = {
 	outDir: './dist',
 	cacheDir: './node_modules/.astro',
 	base: '/',
+  serverIslandHostname: '',
 	trailingSlash: 'ignore',
 	build: {
 		format: 'directory',
@@ -560,6 +561,7 @@ export const AstroConfigSchema = z.object({
 		.optional()
 		.default(ASTRO_CONFIG_DEFAULTS.prerenderConflictBehavior),
 	fonts: z.array(FontFamilySchema).optional(),
+  serverIslandHostname: z.string().optional().default(ASTRO_CONFIG_DEFAULTS.serverIslandHostname),
 	experimental: z
 		.strictObject({
 			advancedRouting: z

packages/astro/src/core/fetch/fetch-state.ts

@@ -409,6 +409,7 @@ export class FetchState implements AstroFetchState {
 			},
 			key: manifest.key,
 			trailingSlash: manifest.trailingSlash,
+      serverIslandHostname: manifest.serverIslandHostname,
 			_experimentalQueuedRendering: {
 				pool: pipeline.nodePool,
 				htmlStringCache: pipeline.htmlStringCache,

packages/astro/src/core/routing/router.ts

@@ -14,6 +14,7 @@ export interface RouterOptions {
 	base: AstroConfig['base'];
 	trailingSlash: AstroConfig['trailingSlash'];
 	buildFormat: NonNullable<AstroConfig['build']>['format'];
+  serverIslandHostname?: AstroConfig['serverIslandHostname'];
 }
 
 interface RouterMatchRoute {
@@ -51,6 +52,7 @@ export class Router {
 	#baseWithoutTrailingSlash: string;
 	#buildFormat: RouterOptions['buildFormat'];
 	#trailingSlash: RouterOptions['trailingSlash'];
+  #serverIslandHostname: RouterOptions['serverIslandHostname'];
 
 	constructor(routes: RouteData[], options: RouterOptions) {
 		// Copy before sorting to avoid mutating the caller's route list.
@@ -60,6 +62,7 @@ export class Router {
 		this.#baseWithoutTrailingSlash = removeTrailingForwardSlash(this.#base);
 		this.#buildFormat = options.buildFormat;
 		this.#trailingSlash = options.trailingSlash;
+    this.#serverIslandHostname = options.serverIslandHostname;
 	}
 
 	/**

packages/astro/src/manifest/serialized.ts

@@ -198,6 +198,7 @@ async function createSerializedManifest(
 		clientDirectives: Array.from(settings.clientDirectives.entries()),
 		renderers: [],
 		base: settings.config.base,
+		serverIslandHostname: settings.config.serverIslandHostname,
 		userAssetsBase: settings.config?.vite?.base,
 		assetsPrefix: settings.config.build.assetsPrefix,
 		site: settings.config.site,

packages/astro/src/runtime/server/render/server-islands.ts

@@ -182,8 +182,9 @@ export class ServerIslandComponent {
 				: await encryptString(key, JSON.stringify(renderedSlots), `slots:${componentId}`);
 
 		const hostId = await this.getHostId();
-		const slash = this.result.base.endsWith('/') ? '' : '/';
-		let serverIslandUrl = `${this.result.base}${slash}_server-islands/${componentId}${this.result.trailingSlash === 'always' ? '/' : ''}`;
+		const serverIslandHostname = this.result.serverIslandHostname?.replace(/\/$/, '') || '';
+		const base = this.result.base === '/' ? '' : this.result.base.replace(/\/$/, '');
+		let serverIslandUrl = `${serverIslandHostname}${base}/_server-islands/${componentId}${this.result.trailingSlash === 'always' ? '/' : ''}`;
 
 		// Determine if its safe to use a GET request
 		const potentialSearchParams = createSearchParams(

packages/astro/src/types/public/config.ts

@@ -229,6 +229,30 @@ export interface AstroUserConfig<
 	 */
 	base?: string;
 
+  /**
+	 * @docs
+	 * @name serverIslandHostname
+	 * @type {string}
+	 * @description
+	 * Sets a hostname or origin prefix to use when Astro fetches server island content.
+	 * This value is prepended to the server island request URL, which is useful when
+	 * you want those requests to go to a different origin (for example, a CDN or
+	 * dedicated API domain) than the page itself.
+	 *
+	 * The value should include the protocol and, if needed, a port. Astro will
+	 * normalize the URL so the server island route is appended correctly.
+	 *
+	 * ```js
+	 * {
+	 *   serverIslandHostname: 'https://cdn.example.com'
+	 * }
+	 * ```
+	 *
+	 * With a base path of `/docs`, a server island request will be fetched from:
+	 * `https://cdn.example.com/docs/_server-islands/...`
+	 */
+	serverIslandHostname?: string;
+
 	/**
 	 * @docs
 	 * @name trailingSlash

packages/astro/src/types/public/internal.ts

@@ -228,6 +228,7 @@ export interface SSRResult {
 	cookies: AstroCookies | undefined;
 	getServerIslandNameMap: () => Promise<Map<string, string>>;
 	trailingSlash: AstroConfig['trailingSlash'];
+  serverIslandHostname?: AstroConfig['serverIslandHostname'];
 	key: Promise<CryptoKey>;
 	_metadata: SSRMetadata;
 	/**

packages/astro/test/units/manifest/serialized.test.ts

@@ -117,6 +117,16 @@ describe('serializedManifestPlugin - dev mode', () => {
 		});
 	});
 
+	describe('serverIslandHostname', () => {
+		it('preserves the configured hostname', async () => {
+			const settings = await createBasicSettings({
+				serverIslandHostname: 'https://example.com',
+			});
+			const manifest = await getManifest(settings);
+			assert.equal(manifest.serverIslandHostname, 'https://example.com');
+		});
+	});
+
 	describe('serverLike', () => {
 		it('is true when buildOutput is server', async () => {
 			const settings = await createBasicSettings({});

packages/astro/test/units/server-islands/server-islands-render.test.ts

@@ -224,6 +224,50 @@ describe('ServerIslandComponent', () => {
 			);
 		});
 
+		it('uses the configured serverIslandHostname as a URL prefix', async () => {
+			const result = await createStubResult({
+				base: '/docs',
+				serverIslandHostname: 'https://cdn.example.com',
+			});
+			const component = new ServerIslandComponent(result, islandProps(), {}, 'Island');
+			const content = await component.getIslandContent();
+			assert.ok(
+				content.includes('https://cdn.example.com/docs/_server-islands/Island'),
+				`server island URL should be prefixed by serverIslandHostname, got: ${content}`,
+			);
+		});
+
+		it('normalizes a trailing slash in serverIslandHostname', async () => {
+			const result = await createStubResult({
+				base: '/docs',
+				serverIslandHostname: 'https://cdn.example.com/',
+			});
+			const component = new ServerIslandComponent(result, islandProps(), {}, 'Island');
+			const content = await component.getIslandContent();
+			assert.ok(
+				content.includes('https://cdn.example.com/docs/_server-islands/Island'),
+				`server island URL should not contain a double slash, got: ${content}`,
+			);
+			assert.ok(
+				!content.includes('https://cdn.example.com//docs/_server-islands/Island'),
+				'server island URL should not double-escape the base path',
+			);
+		});
+
+		it('keeps the relative URL when serverIslandHostname is unset', async () => {
+			const result = await createStubResult({ serverIslandHostname: undefined });
+			const component = new ServerIslandComponent(result, islandProps(), {}, 'Island');
+			const content = await component.getIslandContent();
+			assert.ok(
+				content.includes('/_server-islands/Island'),
+				`server island URL should remain relative when unset, got: ${content}`,
+			);
+			assert.ok(
+				!content.includes('https://') && !content.includes('http://'),
+				'server island URL should not add an absolute origin when unset',
+			);
+		});
+
 		it('appends a trailing slash when trailingSlash is "always"', async () => {
 			const result = await createStubResult({ trailingSlash: 'always' });
 			const component = new ServerIslandComponent(result, islandProps(), {}, 'Island');