Fix public files taking priority over API routes in build (#15331)

matthewp · web-flow · commit 4592be5bb749 · 2026-01-29T09:59:46.000-05:00
diff --git a/.changeset/public-files-priority.md b/.changeset/public-files-priority.md
@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Fixes an issue where API routes would overwrite public files during build. Public files now correctly take priority over generated routes in both dev and build modes.
diff --git a/packages/astro/src/core/build/generate.ts b/packages/astro/src/core/build/generate.ts
@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 import PLimit from 'p-limit';
 import PQueue from 'p-queue';
 import colors from 'piccolore';
@@ -35,6 +36,8 @@ import type { BuildApp } from './app.js';
 import { getOutFile, getOutFolder } from './common.js';
 import { type BuildInternals, hasPrerenderedPages } from './internal.js';
 import type { StaticBuildOptions } from './types.js';
+import type { AstroSettings } from '../../types/astro.js';
+import type { Logger } from '../logger/core.js';
 import { getTimeStat, shouldAppendForwardSlash } from './util.js';
 
 export async function generatePages(
@@ -617,6 +620,9 @@ async function generatePath(
 		routeToHeaders.set(pathname, { headers: responseHeaders, route: integrationRoute });
 	}
 
+	// Public files take priority over generated routes
+	if (checkPublicConflict(outFile, route, settings, logger)) return false;
+
 	await fs.promises.mkdir(outFolder, { recursive: true });
 	await fs.promises.writeFile(outFile, body);
 
@@ -634,3 +640,29 @@ function getPrettyRouteName(route: RouteData): string {
 	}
 	return route.component;
 }
+
+/**
+ * Check if a file exists in the public directory that would conflict with the output file.
+ * Public files take priority over generated routes. Returns true if there's a conflict.
+ */
+function checkPublicConflict(
+	outFile: URL,
+	route: RouteData,
+	settings: AstroSettings,
+	logger: Logger,
+): boolean {
+	const outFilePath = fileURLToPath(outFile);
+	const outRoot = fileURLToPath(
+		settings.buildOutput === 'static' ? settings.config.outDir : settings.config.build.client,
+	);
+	const relativePath = outFilePath.slice(outRoot.length);
+	const publicFilePath = new URL(relativePath, settings.config.publicDir);
+	if (fs.existsSync(publicFilePath)) {
+		logger.warn(
+			'build',
+			`Skipping ${route.component} because a file with the same name exists in the public folder: ${relativePath}`,
+		);
+		return true;
+	}
+	return false;
+}
diff --git a/packages/astro/test/astro-public.test.js b/packages/astro/test/astro-public.test.js
@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import { Writable } from 'node:stream';
-import { before, describe, it } from 'node:test';
+import { after, before, describe, it } from 'node:test';
 import { Logger } from '../dist/core/logger/core.js';
 import { loadFixture } from './test-utils.js';
 
@@ -47,4 +47,36 @@ describe('Public', () => {
 			assert.fail(`Should not have empty chunk warning, but got: ${emptyChunkWarning.message}`);
 		}
 	});
+
+	it('public file takes priority over API route in build', async () => {
+		// When both public/robots.txt and src/pages/robots.txt.ts exist,
+		// the public file should take priority
+		const robotsTxt = await fixture.readFile('/robots.txt');
+		assert.match(robotsTxt, /Disallow: \/admin\//, 'Should contain public file content');
+		assert.doesNotMatch(robotsTxt, /Disallow: \/\n/, 'Should not contain API route content');
+	});
+});
+
+describe('Public (dev)', () => {
+	let fixture;
+	let devServer;
+
+	before(async () => {
+		fixture = await loadFixture({ root: './fixtures/astro-public/' });
+		devServer = await fixture.startDevServer();
+	});
+
+	after(async () => {
+		await devServer.stop();
+	});
+
+	it('public file takes priority over API route in dev', async () => {
+		// When both public/robots.txt and src/pages/robots.txt.ts exist,
+		// the public file should take priority
+		const response = await fixture.fetch('/robots.txt');
+		assert.equal(response.status, 200);
+		const text = await response.text();
+		assert.match(text, /Disallow: \/admin\//, 'Should contain public file content');
+		assert.doesNotMatch(text, /Disallow: \/\n/, 'Should not contain API route content');
+	});
 });
diff --git a/packages/astro/test/fixtures/astro-public/public/robots.txt b/packages/astro/test/fixtures/astro-public/public/robots.txt
@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /admin/
diff --git a/packages/astro/test/fixtures/astro-public/src/pages/robots.txt.ts b/packages/astro/test/fixtures/astro-public/src/pages/robots.txt.ts
@@ -0,0 +1,5 @@
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = () => {
+	return new Response('User-agent: *\nDisallow: /\n');
+};

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'astro': patch
 +---
++
 +Fixes an issue where API routes would overwrite public files during build. Public files now correctly take priority over generated routes in both dev and build modes.