new: Document failOnPrerenderConflict experimental flag

[Fryuni]

Description

Document new experimental flag to fail on multiple routes prerendering the same page instead of showing a warning.

For Astro version: 5.14. See astro PR #14206.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	a76f53e
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68c1c4ac9a854b000849730e
😎 Deploy Preview	https://deploy-preview-12237--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/reference/experimental-flags/fail-on-prerender-conflict.mdx	Localization added, will be marked as complete.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[sarah11918]

Looks great, see my BIG comment for my BIG suggestion below! 😂

[sarah11918]

Suggested change

	Multiple dynamic routes can result in the same output path, for example `/blog/[slug]` and `/blog/[...all]` both could try to prerender the `/blog/post-1` path. In such cases, Astro will warn you about the conflict during build and render only the [highest priority route](/en/guides/routing/#route-priority-order) for the conflicting path. With this flag set, the build will instead fail immediately with an error.
	This will be the default behavior in Astro 6.
	Enable it in your `astro.config.mjs`:
	```js
	// astro.config.mjs
	defineConfig({
	experimental: {
	failOnPrerenderConflict: true,
	},
	});
	```
	Multiple dynamic routes can result in the same output path, for example `/blog/[slug]` and `/blog/[...all]` both could try to prerender the `/blog/post-1` path. In such cases, Astro currently warns you about the conflict during build and renders only the [highest priority route](/en/guides/routing/#route-priority-order) for the conflicting path. This allows your site to build successfully, although you may discover that some pages are rendered by unexpected routes.
	With this experimental flag set, the build will instead fail immediately with an error. This will require you to resolve conflicts immediately, and will ensure that Astro is building your routes as you intend.
	To enable this behavior, add the `experimental.failOnPrerenderConflict` feature flag to your Astro config:
	```js title="astro.config.mjs" ins={4-6}
	import { defineConfig } from "astro/config"
	defineConfig({
	experimental: {
	failOnPrerenderConflict: true,
	},
	});
	```
	In a future major version, Astro will no longer successfully build when prerendered route conflicts are found and will require you to resolve the conflict prior to building, but you can opt in to the future behavior early using the `experimental.failOnPrerenderConflict` flag.
	## Usage
	After enabling this flag, you may encounter an error about conflicting prerendered routes when you attempt to build your project. If this happens, you will need to update one or more of your [dynamic routes](/en/guides/routing/#dynamic-routes) to avoid ambigous routing.

This looks great!!

This is one big suggestion because I wanted to do some rearranging (more than actually editing). BUT, I did try to add some context as an example of "level of detail" I think might be useful.

Also, after this, I would consider showing a simple example of resolving a conflict. It's one thing to tell people "both of these routes are trying to render this page", but even better to show a typical conflict and how someone will need to change their project to be able to build!

[Fryuni]

Should we add that here or should we add a "troubleshooting" section on the routing page explaining the warning and how to fix it?

[sarah11918]

@Fryuni For now, while this is experimental, (and people flipping this on are the only people who are going to need it, and might very well need it!) it should go here!

All experimental documentation is contained to its one page. When this is no longer experimental and is the default, we can redistribute whatever content needed is on this page. (e.g. we might update the routing priority page with a one-liner, as you say, this could go in troubleshooting...)

[Fryuni]

Just to be clear. The experimental flag is to turn the warning into an error. The warning is for everyone.

[sarah11918]

Right, everyone gets the warning right now, but the flag means people's builds will fail.

Oh, I get you know -- you mean something in troubleshooting so people can fix the warning that they are currently getting! Actually, now maybe that does seem helpful. And we can link to it from the existing warning maybe? There's nothing someone would do to fix the existing warning that they wouldn't do to fix a broken build in this case, right? The advice is exactly the same?

I see what you were thinking. I also think that people who might have ignored the warning (maybe it didn't really matter to them or affect their project in a way they cared about) will now have failing builds, and these people need to realize this maybe even before deciding to enable the flag. So this still feels like important information about this feature in particular. So I might still include the "how to solve this" in the PR changeset for the minor release maybe, even if we put this in troubleshooting in the docs?

I could go either way on this PR, but now I think troubleshooting is not a bad idea, and might help more people sooner, so not opposed to adding it there! Great idea!

[Fryuni]

There's nothing someone would do to fix the existing warning that they wouldn't do to fix a broken build in this case, right? The advice is exactly the same?

Correct. We had a discussion about this and decided to not make it the default in the future. It will be experimental to set it as an error and once stabilized it will be a normal flag, but the default will remain as a warning.