Improve trailingSlash experience

[bluwy]

Body

Summary

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

Note

17 Jan 2025: I've made some significant updates to the proposed changes since the last update. Instead of having trailingSlash apply to pages and endpoints. The changes now reflects individual options for configuring trailing slashes for pages and endpoints instead. This was changed as pages and endpoints have different ideal setups regarding trailing slashes.

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)

Pages vs endpoints

It's also worth sheding some light about how trailing slashes affects pages vs endpoints. Pages are files that emit HTML, while endpoints are usually server handlers that respond to dynamic requests. If endpoints are prerendered, then their results are written to the file as is (e.g. src/pages/dir/foo.ts -> dist/dir/foo, src/pages/dir/data.json -> dist/dir/data.json).

Trailing slashes often only matter for pages, not endpoints. The ending / usually implies index.html. So for endpoints, we want to make sure that accessing with or without trailing slashes is still possible and shouldn't be a big deal in practice.

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)

Note

Below lists 2 proposed changes, but they all achieve the same behaviour. Just different ways to model the API.

Proposed changes 1

1. New default trailingSlash config:

   type TrailingSlashStyle = 'always' | 'never' | 'ignore'
   trailingSlash: TrailingSlashStyle | { page: TrailingSlashStyle, endpoint: TrailingSlashStyle }
   
   // default: { page: 'always', endpoint: 'ignore' }

   trailingSlash.page is always which matches the behaviour of the current build.format: 'directory' default. In practice, this should cause a breaking change of the file output. Same for endpoints too as it's still ignore.

2. build.format is removed, and should be configured through trailingSlash.page instead.

   • 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' (a little confusing but could polished up later)

3. For easier migration, we can deprecate build.format for now, but auto-set trailingSlash.page respectively based on the list above. If trailingSlash.page is already set but conflicts with build.format, we could probably emit a warning.

Proposed changes 2

1. build.format only applies to pages, and trailingSlash only applies to endpoints.
2. We don't need to change the defaults, but we'd have to change our code to use the correct config option to add/remove trailing slashes depending if it's a page or endpoint.
3. Optionally, we could then remove the trailingSlash option and only assume ignore for endpoints. Usually endpoint trailing slash doesn't really matter so it might be good to have one less option to think about how it's applied?

Personally I think "proposed changes 1" makes the API feel more consistent, but either way works well enough if documented.

[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'
}

[fweth]

I also think the behavior of Astro.url is not ideal when trailingSlash: "ignore" is set, as it is by default. In the development server, Astro.url returns the exact string that you enter in the browser bar, with or without a trailing slash (except for the root). This can lead to bugs where different content is rendered depending on the presence of a trailing slash. However, at build time, Astro.url always includes the trailing slash. As a result, running npm run preview might display different content than npm run dev if the trailing slash is missing from the URL. I personally believe that in development mode, Astro.url should always include the trailing slash, regardless of the actual URL requested by the browser, to better mimic the production scenario.

[ematipico]

While I agree with you, there's a reason why the option is called ignore. It's meant for cases when you don't care about the presence of slash being there or not. That's probably why the team didn't bother about consistency when this option is enabled.

But it seems you have opinions, and you prefer the ignore option. Why don't you use the other options? Is there some use case you didn't mention?

[fweth]

Since most hosting providers ignore the trailing slash and serve both example.com/foo and example.com/foo/ (while serving the same content, as Astro would never build both foo.html and foo/index.html), I would prefer the same behavior for the development server. Therefore, I don't want to enable a strict option where one of the two variants is not served.

In general, I believe the current default behavior can be problematic because the differences between the development server and the build may be subtle, and you might not even think about it since it's the default setting. You spend more time in the development server checking for content errors, so issues that only appear in the build might be easily overlooked.

As I mentioned, I think all options should align the development server behavior as closely as possible to the preview behavior, and, subsequently, to the production behavior for matching environments. The strict options already do a great job, but the ignore option introduces a dev server behavior that no production environment would ever replicate, as you will never have example.com/foo and example.com/foo/ serve different content.

Lastly, I believe the term ignore is misleading because it suggests that the trailing slash is not processed at all, which is not the case.

[bluwy]

"ignore" is something this discussion doesn't quite cover extensively yet and will probably be dug deeper separately in the future.

TLDR: `ignore` should infer from source directory structure

I agree that in reality, if you have "ignore" Astro should output both foo.html and foo/index.html so it can be accessed in both paths, however many hosting providers or file servers don't really serve the right file anyways, so the intention doesn't really work in practice.

Plus, I think people prefer to keep a single file output instead, so the other idea is to infer the source directory structure and get the trailing slash from there instead.

• src/pages/foo/index.astro - Needs trailing slash
• src/pages/foo.astro - No trailing slash

This is kinda what build.format: 'preserve' aims to do, but it's not correctly applied for trailingSlash: 'ignore' yet, which is something to polish out in the future. I think this may be the better heuristic than always appending a trailing slash, otherwise you should be using trailingSlash: 'always' instead.

TLDR: `ignore` should be discouraged

But alas, something I want to improve on the docs for as well is to discourage trailingSlash: 'ignore'. Not only it opens up a can of worms, but it hurts SEO too without some canonical links setup, which once you've figure all that out, it might've been better to choose a single trailing slash behaviour in the first place. However, this only applies to pages in general. Endpoints (or rather non-HTML pages) don't have many issues with trailing slash anyways. The draft I'm working on will allow you to specify the behaviour differently between pages and endpoints.

[fweth]

Thank you for the reply! Just to clarify, I don't think Astro should create both foo.html and foo/index.html, at least not by default. I just miss a sensible default where you don't get an error in the dev server when you put or not put the slash in the URL (like it is the case in most production environments), but Astro.url is rendered with a consistent value, independent from the use of a trailing slash in the actual URL (what I expect from ignore).

Sorry if I made the impression that I prefer the trailing slash in my first comment, I just think that the dev server should behave like the build process, so either put the slash in Astro.url always or never or depending on the directory structure, all three options seem fine to me.