build.format / trailingSlash / Astro.url / Astro.props.url interactions all seem bolloxed

[egnor]

Astro Info

Astro                    v5.1.1
Node                     v22.4.0
System                   Linux (x64)
Package Manager          npm
Output                   static
Adapter                  none
Integrations             @astrojs/sitemap

If this issue only occurs in one browser, which browser is a problem?

(browser independent)

Describe the Bug

I am trying to figure out how source files and generated files and URLs interrelate with the various choices for build.format (directory, file, and preserve) and trailingSlash (always, never, and ignore) and nothing makes any sense.

At the URL below I've made a simple exercise case that shows Astro.url and Astro.props.url (and the corresponding .url property of an imported page) for directory-index and non-directory index files, with a site base of /site_base/ (note trailing slash).

Here's what I get:

#	format	trailingSlash	source file	output file	Astro.url dev	Astro.url build	Astro.props.url
1	directory	always	index.md	index.html	http://localhost:4321/site_base/	https://site.domain/site_base/	/site_base/
2	directory	ignore	index.md	index.html	http://localhost:4321/site_base/	https://site.domain/site_base/	/site_base
3	file	never	index.md	index.html	http://localhost:4321/site_base/	https://site.domain/site_base	/site_base.html
4	file	ignore	index.md	index.html	http://localhost:4321/site_base/	https://site.domain/site_base/	/site_base.html
5	preserve	ignore	index.md	index.html	http://localhost:4321/site_base/	https://site.domain/site_base/	/site_base
6	directory	always	another_page.md	another_page/index.html	http://localhost:4321/site_base/another_page/	https://site.domain/site_base/another_page/	/site_base/another_page/
7	directory	ignore	another_page.md	another_page/index.html	http://localhost:4321/site_base/another_page/	https://site.domain/site_base/another_page/	/site_base/another_page
8	file	never	another_page.md	another_page.html	http://localhost:4321/site_base/another_page.html	https://site.domain/site_base/another_page.html	/site_base/another_page.html
9	file	ignore	another_page.md	another_page.html	http://localhost:4321/site_base/another_page.html	https://site.domain/site_base/another_page.html	/site_base/another_page.html
10	preserve	ignore	another_page.md	another_page.html	http://localhost:4321/site_base/another_page.html	https://site.domain/site_base/another_page/	/site_base/another_page

Some things don't make sense to me?

• rows 1/2 and 6/7: weird that changing Astro.props.url from always to ignore drops the trailing slash from Astro.props.url but NOT from Astro.url?
• row 3: presence of trailing slash in Astro.url differs between dev and prod??
• rows 3, 4: with a site base of /site_base/ and a generated file of index.html, Astro.props.url of /site_base.html seems completely wrong.
• row 10: in prod, but NOT dev, Astro.url uses another_page/ instead of another_page.html; meanwhile Astro.props.url uses another_page (no trailing slash)!
• most: it's generally surprising that the pathname of Astro.url doesn't match Astro.props.url.

Also, when using file output mode, the dev server has different behavior if you request .../another_file vs .../another_file/ vs .../another_file.html, which can't be right since in prod those would all be the same static file. (For the above examples, I always requested .../another_file.html.)

Finally, very strange things happen with file+always or directory+never, but I'm ignoring that because those are arguably not very sensible combinations??

What's the expected result?

A sane, consistent, and well documented approach to the necessary three way mapping between source file layout, output file layout, and assumed URL, without strange variations.

I'm sort of surprised I don't see more people having problems with this, maybe it's because I'm missing something major? Or I guess relatively few people access these metadata fields, people just hardcode URLs?

This is related to the question of how to construct links in Astro -- the docs just say to link to the URL, but to do that you need to know what the URL should be.

Potentially related:

• 🐛 BUG: Astro.url.pathname is missing trailing slash on prod build #4190
• Astro.url.pathname includes trailing dash when building for SSG but not on dev mode #5630
• sitemap does not respect build.format = "file" #7422
• getLocaleByPath(Astro.url.pathname) not working as expected #10017
• Astro.url shows .html file extension when it shouldn't #10996
• Astro.URL not supported when building with build.format='preserve' #11107
• Sitemap url and Astro.url mismatch with build.format file #11575

Link to Minimal Reproducible Example

https://github.com/egnor/astro_bug_report

Participation

• I am willing to submit a pull request for this issue.

[my-astro]

rows 1/2 and 6/7: weird that changing Astro.props.url from always to ignore drops the trailing slash from Astro.props.url but NOT from Astro.url?

Directories will always have trailingSlash. Docs: https://docs.astro.build/en/reference/configuration-reference/#effect-on-astrourl

P.s. Also very handy table, should be added to docs, thanks!

[my-astro]

@egnor My website is configured like your row number 3 and I do not have a trailing slash in dev mode with Astro.url.

To test it I’ve created a page src/pages/asd.astro containing:

---
const url = Astro.url;
---

{url}

The page rendered http://localhost:4321/asd

P.s. trailingSlash config option impacts only dev:

Set the route matching behavior of the dev server.
from docs: https://docs.astro.build/en/reference/configuration-reference/#trailingslash

[egnor]

@egnor wrote

rows 1/2 and 6/7: weird that changing Astro.props.url from always to ignore drops the trailing slash from Astro.props.url but NOT from Astro.url?

@my-astro replies

Directories will always have trailingSlash. Docs: https://docs.astro.build/en/reference/configuration-reference/#effect-on-astrourl

I'm sorry, I don't understand how that addresses the inconsistency?

@my-astro wrote

@egnor My website is configured like your row number 3 and I do not have a trailing slash in dev mode with Astro.url.

I think that's row 8, not row 3? Since you're accessing /asd.* rather than /index.*?

(Also, you're using an .astro file rather than a .md file, but that shouldn't matter here, right? If it does, that's even more confusing.)

When you say "The page rendered http://localhost:4321/asd", I assume that's using the dev server and accessing /asd? That path with no .html suffix wouldn't work on a production build without a server that supports some content autonegotiation, and in any case I think you'll find that build output generates https://your.site.name/asd.html as the Astro.url value.

@my-astro wrote

P.s. trailingSlash config option impacts only dev:

Set the route matching behavior of the dev server.
from docs: https://docs.astro.build/en/reference/configuration-reference/#trailingslash

I think that's wrong? For example, see the difference between rows 3 and 4 in the "Astro.url build" column -- in fact, trailingSlash seems to affect production page generation.

Also see #7808 (comment) and other discussions about trailingSlash.

[bluwy]

Generally, I agree that the behavior now is not really consistent. The table is really helpful though in identifying the problematic parts. Thanks for taking the time to test them out. I think we need to break it down a bit to some actionable parts:

1. The output file is correctly reflecting build.format, so I think we don't have to change anything there.
2. How trailingSlash and build.format interacts is a bit finicky, but there's some plans to simplify that a bit.
3. Astro.url (dev/prod) and Astro.props.url needs to be consistent. We should address the inconsistencies you pointed out.
4. How base affects trailing slash for root files. Personally I think you'd never go wrong by always prepending a trailing slash for base root path, like https://site.domain/site_base/ regardless of any config option, as otherwise any relative links would've pointed outside the base, which is likely incorrect. But we'll need to investigate a way still to allow opting into this edge case and possibly be a breaking change.

It would be hard to fix them all at once, so maybe there should be separate bug reports for each problems. Or a discussion at https://github.com/withastro/roadmap if it requires some refactoring or new features.

[ascorbic]

I'm going to close this for the reason @bluwy gave: it covers multiple issues so isn't actionable like this. However I agree that it's a super useful table so thanks for that. I referred to it when working on #12994, which will address several of the issues by ensuring inconsistent paths are redirected. It will probably miss some parts. I would encourage you to try the preview release linked in the PR and see what it covers. If there are remaining bugs then your best bet is to open new issues for the specific bugs.