Document Astro.originPathname

[TheOtterlord]

Document the originPathname context, implemented in https://github.com/withastro/astro/pull/12373 and first released in [email protected]

[netlify[bot]]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	377ca360781a50fc58dd7adabbb0892f5d1efb99
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/6883f649f5d0910008f51f3c
😎 Deploy Preview	https://deploy-preview-11610--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/api-reference.mdx	Source changed, localizations will be marked as outdated.

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]

Thanks @TheOtterlord !

I'm wondering whether there should be mention of/link to this in the rewrite() entry? (it's specific to rewrites only? not redirects?)

Also, given our description of rewrites:

rewrite() allows you to serve content from a different URL or path without redirecting the browser to a new page.

It doesn't seem like Astro.url.pathname and Astro.originPathname would be different? I would expect url to match the URL in my browser bar, and if we haven't redirected the browser to a new path (only pulled content in from a new path), then do either of the descriptions for redirect or url have to change?

[TheOtterlord]

I'm wondering whether there should be mention of/link to this in the rewrite() entry? (it's specific to rewrites only? not redirects?)

Yes, this is specific to rewrites. I positioned it under rewrite since it's related, but we can also find a way mention it there if it's helpful.

It doesn't seem like Astro.url.pathname and Astro.originPathname would be different? I would expect url to match the URL in my browser bar, and if we haven't redirected the browser to a new path (only pulled content in from a new path), then do either of the descriptions for redirect or url have to change?

Astro.url.pathname is the URL of the page you rewrite to, which is why originPathname exists (afaik). So Astro.originalPathname matches the path you'd see in the browser, whereas Astro.url.pathname would be the /404 or whatever you called rewrite() with.

[sarah11918]

So, my confusion is that this is what we say about rewrites in the routing guide:

A rewrite allows you to serve a different route without redirecting the browser to a different page. The browser will show the original address in the URL bar, but will instead display the content of the URL provided to Astro.rewrite().

So, I'm trying to wrap my head around what I think the above says:

• someone requests URL-a (is this originPath? the original pathname requested, before rewrites were applied?)
• according to what we say about rewrites, the browser bar displays that you're on URL-a (what I'd expect url.pathname to show because that is the path you can see?) but shows the content that exists at URL-b.
• is URL-b the url.pathname since it's the location of the content you're seeing (but not actually the URL pathname of the page you're on right now? If that's the case, if url.pathname can be a different address then you are currently visiting, then I think that needs more explaining?

I get that we request one path and see the content for a different one, and that there's a "ask for this, get this" relationship. But, if the URL of the initial request, and the one shown in the browser are the same (because you didn't redirect, you just put different content at the requested path), then I would expect displaying originPath (the path I requested) and url.pathname (the URL I see in my browser tab, because I did in fact go there, and that wasn't changed on me) to be the same.

This is what I'm trying to figure out, and whether any other explanations need to change, because the example you added here makes me think that those would return two different URL paths, but I'm trying to figure out how that would be. 😅

[sarah11918]

Discussed on Talking and Doc'ing 2025-06-05:

• should we have "Astro/context" tabs here too like the other entries?
• should we explicitly talk about a new rendering phase being triggered, like we do in the Middleware guide?
• shared the implementation PR for additional context https://github.com/withastro/astro/pull/12373
• this is a great reference entry, but realizing we haven't documented this anywhere, means we don't have any place where the more why/use case info is included. So, this can feel "accurate" and "useful" but still not feel "fully documented" and truly helpful to readers.

@TheOtterlord - see which of the above technical points (e.g. adding tabs for Astro/context) you want to include here, and we can consider whether maybe we need something added to the Middleware guide showing this used, but get this helpful, accurate reference merged!

[ArmandPhilippot]

Related to T&D, I just found a use case in the current docs: https://docs.astro.build/en/guides/actions/#advanced-persist-action-results-with-a-session but we don't explicitly tell why we use Astro.originPathname. I guess this example would fail using Astro.url.pathname if someone had configured a rewrite?

Maybe we can do something around that regarding:

we don't have any place where the more why/use case info is included

[sarah11918]

Gentle ping @TheOtterlord that you might have all the info here you're going to get, and I trust you to make a great decision and just merge!

[TheOtterlord]

Thanks. This keeps getting lost in my notifications :sweat_smile:

Will get to this tonight!

[TheOtterlord]

Haha, oops. Was experimenting with other things in the background :sweat_smile: Will undo that and merge this if it's good as-is