Improve trailingSlash experience

[bluwy]

Body

Summary

Make build.format default value as "preserve" and merge build.format into trailingSlash.

NOTE: This proposal only talks about pages, not endpoints. In Astro 5, endpoints should not be affected by trailingSlash.

Background & Motivation

build.format and trailingSlash are closely related. The way you build your pages (as files or directories) affect whether you need a trailing slash to access them or not.

• file.html can only be accessed from example.com/file
• dir/index.html can only be accessed from example.com/dir/

The slashes are important as they affect how relative links are resolved on the webpage. You can't force file.html to be accessed from example.com/file/ for example without breaking relative links.

Tricky workaround

Technically above can be kinda solved if you generate relative links with the anticipation of accessing from example.com/file/, however it can go wrong in, e.g. SSG, where deployment platforms may not allow you to access file.html this way in the first place, you need SSR (as a custom server) to help with this.

We try to avoid users hitting this footgun by suggesting a pair of build.format and trailingSlash configs: https://docs.astro.build/en/reference/configuration-reference/#effect-on-astrourl. The sour thing however is that our default options for both are already conflicting.

build.format	trailingSlash
file	never
directory (default)	always
preserve	ignore (default)

Goals

• A single config for trailing slash and how pages are built (as files or directories)
• More predictable trailing slashes for users
• An easy way to migrate (as this is likely breaking)

Example (proposed changes)

1. Make trailingSlash: 'always' the default. This reflects the build.format: 'preserve' existing default.
2. Merge build.format into trailingSlash, keeping the existing enums of trailingSlash
   • If you want build.format: 'directory', set trailingSlash: 'always'
   • If you want build.format: 'file', set trailingSlash: 'never'
   • If you want build.format: 'preserve', set trailingSlash: 'ignore'
3. For easier migration, we probably can't remove build.format completely but it'll be marked deprecated. We should warn in runtime if that option is used. And the old behaviour needs to be kept but no longer tested (?).

EDIT: Updated proposed changes to have trailingSlash: 'always' as default.

[lorenzolewis]

+1 to anything in this area to make it more clear. I remember this was an area I struggled with when first getting started with Astro. Every time I pick up a different Astro project I find I need to re-learn these bits as well because they aren't 100% clear.

Probably not in the scope of this, but having a way to make relative links more easily useable would be a win. I often see we suggest to people to use a full URL with a beginning slash because this area is difficult to explain and troubleshoot. This is honestly more of an issue with HTML links not being the same as file system links, but any way that Astro could make this easier for end users would be appreciated.

[bluwy]

That's definitely worth an exploration after we nail down how trailingSlash works, like someway to typecheck these relative links similar to https://github.com/florian-lefebvre/astro-typed-links. Also, I'm looking forward for a stepping stone for better relative base support.

[lorenzolewis]

Amazing to hear! Figured it wasn't covered in this but falls in this general area of Astro DX

[florian-lefebvre]

If that can help there's an integration for relative links https://github.com/ixkaito/astro-relative-links

[delucis]

Linking a helpful guide to different deployment platforms: https://github.com/slorber/trailing-slash-guide

Noting also that Starlight uses build.format and trailingSlash to decide how to format links (source). I think the main difference is that we use build.format: 'file' as a proxy for deciding if you want .html in your links or not. I’d guess a change here would likely require us to have a more explicit linkFormat option in Starlight itself. (Not necessarily a reason NOT to do this, just sharing for context.)

[bluwy]

Yup that repo has been really helpful in the past! I've worked on having Vite align on it completely, so hoping to do the same for Astro here with the new default.

About linkFormat, seems like we need it for Vercel's cleanUrls option. Quite annoying that it doesn't have an undefined option that works like Netlify 🥲 Otherwise we could get away with never adding the .html and index.html and most webservers should be able to serve still.

[delucis]

Yeah, although I think some people actually want to serve and link with .html? It feels unusual to me given how common extension-less URLs have become (also best practice to avoid the issue of stuff like /index.php suddenly no longer working because the site changed stack), but I guess some people still like it.

[bluwy]

Yeah I think it comes down to personal preference and a full URL would indeed be correct and should never go wrong. Personally example.com/blog/ is much cleaner than example.com/blog/index.html 😄

[matthewp]

From the PR: withastro/astro#11922

---

My initial thought is that pushing trailingSlash: 'always' is pushing an aesthetic preference onto people and it might turn some people away.

@bluwy said in reply:

I don't think the RFC discussion is only about build.format: 'file', it's for both file and directory. You need them to match this way to prevent relative path issues

If you build your file to dist/foo/index.html, you cannot access it with example.com/foo (no trailing slash, which 'ignore' by default allows).

Which web server doesn't allow this? I just tested with python -m http.server and it did a 302 redirect to the trailing slash version, is that what you mean?

[bluwy]

Which web server doesn't allow this?

I think by "you cannot access it", it's more of "you cannot access it without having relative links issue" 😅

So in some hosts, you can access it, but it will lead to incorrect behaviour. For example at https://github.com/slorber/trailing-slash-guide?tab=readme-ov-file#summary (/folder column), you'd notice that some hosts do the redirect behaviour like the python server, which is good.

But some hosts allow serving the foo/index.html under /foo, and this will lead to relative links being incorrect because it's missing the trailing slash in the browser.

[matthewp]

Proposed default:

trailingSlash: {
  page: 'always',
  endpoint: 'ignore'
}

trailingSlash: 'never' // shortcut for..
trailingSlash: {
  page: 'never',
  endpoint: 'never'
}