Prevent Cloudflare build issues due to Node.js builtins usage (#3341)

Co-authored-by: delucis <[email protected]>
Co-authored-by: Chris Swithinbank <[email protected]>

Author: HiDeoo

.changeset/olive-weeks-rest.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': patch
+---
+
+Prevents potential build issues with the Astro Cloudflare adapter due to the dependency on Node.js builtins.

packages/starlight/__e2e__/fixtures/no-node-builtins/astro.config.mjs

@@ -0,0 +1,16 @@
+// @ts-check
+import starlight from '@astrojs/starlight';
+import { defineConfig } from 'astro/config';
+import { preventNodeBuiltinDependencyPlugin } from './src/noNodeModule';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'No Node Builtins',
+			pagefind: false,
+		}),
+	],
+	vite: {
+		plugins: [preventNodeBuiltinDependencyPlugin()],
+	},
+});

packages/starlight/__e2e__/fixtures/no-node-builtins/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@e2e/no-node-builtins",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/starlight": "workspace:*",
+    "astro": "^5.6.1"
+  }
+}

packages/starlight/__e2e__/fixtures/no-node-builtins/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

packages/starlight/__e2e__/fixtures/no-node-builtins/src/content/docs/index.md

@@ -0,0 +1,5 @@
+---
+title: Home Page
+---
+
+Home page content

packages/starlight/__e2e__/fixtures/no-node-builtins/src/noNodeModule.ts

@@ -0,0 +1,36 @@
+import type { ViteUserConfig } from 'astro';
+import { builtinModules } from 'node:module';
+
+const nodeModules = builtinModules.map((name) => [name, `node:${name}`]).flat();
+
+/**
+ * A Vite plugin used to verify that the final bundle does not have a hard dependency on Node.js
+ * builtins due to Starlight.
+ * This is to ensure that Starlight can run on platforms like Cloudflare.
+ *
+ * @see https://github.com/withastro/astro/blob/8491aa56e8685677af8458ff1c5a80d6461413f8/packages/astro/test/test-plugins.js
+ */
+export function preventNodeBuiltinDependencyPlugin(): NonNullable<
+	ViteUserConfig['plugins']
+>[number] {
+	return {
+		name: 'verify-no-node-stuff',
+		generateBundle() {
+			nodeModules.forEach((name) => {
+				const importers = this.getModuleInfo(name)?.importers || [];
+				const starlightPath = new URL('../../../../', import.meta.url).pathname;
+				const nodeStarlightImport = importers.find((importer) =>
+					importer.startsWith(starlightPath)
+				);
+
+				if (nodeStarlightImport) {
+					throw new Error(
+						'A node builtin dependency imported by Starlight was found in the production bundle:\n\n' +
+							` - Node builtin: '${name}'\n` +
+							` - Importer: ${nodeStarlightImport}\n`
+					);
+				}
+			});
+		},
+	};
+}

packages/starlight/__e2e__/no-node-builtins.test.ts

@@ -0,0 +1,10 @@
+import { expect, testFactory } from './test-utils';
+
+const test = testFactory('./fixtures/no-node-builtins/');
+
+test('builds without any dependencies on Node.js builtins', async ({ page, getProdServer }) => {
+	const starlight = await getProdServer();
+	await starlight.goto('/');
+
+	await expect(page.getByText('Home page content')).toBeVisible();
+});

packages/starlight/__tests__/remark-rehype/anchor-links.test.ts

@@ -4,6 +4,7 @@ import { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../../utils/user-config';
 import { absolutePathToLang as getAbsolutePathFromLang } from '../../integrations/shared/absolutePathToLang';
 import { starlightAutolinkHeadings } from '../../integrations/heading-links';
+import { getCollectionPosixPath } from '../../utils/collection-fs';
 
 const starlightConfig = StarlightConfigSchema.parse({
 	title: 'Anchor Links Tests',
@@ -23,7 +24,10 @@ const useTranslations = createTranslationSystemFromFs(
 );
 
 function absolutePathToLang(path: string) {
-	return getAbsolutePathFromLang(path, { astroConfig, starlightConfig });
+	return getAbsolutePathFromLang(path, {
+		docsPath: getCollectionPosixPath('docs', astroConfig.srcDir),
+		starlightConfig,
+	});
 }
 
 const processor = await createMarkdownProcessor({

packages/starlight/__tests__/remark-rehype/asides.test.ts

@@ -7,6 +7,7 @@ import { createTranslationSystemFromFs } from '../../utils/translations-fs';
 import { StarlightConfigSchema, type StarlightUserConfig } from '../../utils/user-config';
 import { BuiltInDefaultLocale } from '../../utils/i18n';
 import { absolutePathToLang as getAbsolutePathFromLang } from '../../integrations/shared/absolutePathToLang';
+import { getCollectionPosixPath } from '../../utils/collection-fs';
 
 const starlightConfig = StarlightConfigSchema.parse({
 	title: 'Asides Tests',
@@ -26,7 +27,10 @@ const useTranslations = createTranslationSystemFromFs(
 );
 
 function absolutePathToLang(path: string) {
-	return getAbsolutePathFromLang(path, { astroConfig, starlightConfig });
+	return getAbsolutePathFromLang(path, {
+		docsPath: getCollectionPosixPath('docs', astroConfig.srcDir),
+		starlightConfig,
+	});
 }
 
 const processor = await createMarkdownProcessor({

packages/starlight/index.ts

@@ -92,7 +92,9 @@ export default function StarlightIntegration(
 				// config or by a plugin.
 				const allIntegrations = [...config.integrations, ...integrations];
 				if (!allIntegrations.find(({ name }) => name === 'astro-expressive-code')) {
-					integrations.push(...starlightExpressiveCode({ starlightConfig, useTranslations }));
+					integrations.push(
+						...starlightExpressiveCode({ astroConfig: config, starlightConfig, useTranslations })
+					);
 				}
 				if (!allIntegrations.find(({ name }) => name === '@astrojs/sitemap')) {
 					integrations.push(starlightSitemap(starlightConfig));