✨ Separate where a build is hosted from the url it is published at - #22
Merged
Merged
Conversation
`--base` answered two questions at once: where these bytes live, and what this content is called. They coincide for an ordinary site and come apart the moment one is served from one origin and read at another — Effection is hosted at effection.netlify.app and published at frontside.com/effection. Getting the canonical right meant pointing `--base` at the published url, which dragged every other url along with it. thefrontside/effection#1248 did exactly that, and the sitemap went with it: frontside.com prefixes `/effection` onto a proxied sitemap, the entries already carried it, and 519 urls 404'd. `--canonical` splits the two. Urls that name the page — a canonical link, the `og:url` that says the same thing, an `alternate` saying it for another language — rebase onto it. Navigation, assets and the sitemap stay on `--base`, so the build still browses at the address it is served from. Textual bodies follow `--canonical`: llms.txt is a map telling a reader where the docs live, not a page of the site. It defaults to `--base`, so every existing invocation is unchanged, and a site hosted where it is published says so by saying nothing. Closes #21.
cowboyd
approved these changes
Sep 28, 2026
taras
added a commit
to thefrontside/interactors
that referenced
this pull request
Sep 28, 2026
Moving `--base` to frontside.com got the canonical right by moving every other url with it: the sitemap, the social card, and any absolute link. That is what broke frontside.com's deploy when Effection did the same, and it left the Netlify build claiming to be somewhere it is not served from. thefrontside/staticalize#22 split the two, released in 0.3.1. `--base` is where the bytes are again, and `--canonical` is the address readers arrive at, so a preview stays browsable on its own alias while still telling search engines to index production. 0.3.1 also restored the default for `--retries`, so the flag 0.3.0 forced us to pass goes away with it.
taras
added a commit
to thefrontside/graphgen
that referenced
this pull request
Sep 28, 2026
Moving `--base` to frontside.com got the canonical right by moving every other url with it, including the sitemap. That is what broke frontside.com's deploy when Effection did the same, and it left the Netlify build claiming to be somewhere it is not served from. thefrontside/staticalize#22 split the two, released in 0.3.1. `--base` is where the bytes are again, and `--canonical` is the address readers arrive at. The canonical link added in the previous commit is what 0.3.1 rewrites; without it there would be nothing here to name the published page. 0.3.1 also restored the default for `--retries`, so the flag 0.3.0 forced us to pass goes away with it.
This was referenced Sep 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #21.
Motivation
--baseanswers two questions at once:a[href],[src]and asset links point at<link rel="canonical">and<meta property="og:url">claimThey coincide for an ordinary site, which is why nothing forced them apart. They
come apart the moment a site is served from one origin and read at another:
Effection is hosted at
effection.netlify.appand published atfrontside.com/effection, and the same holds for Interactors and Graphgen.Getting the canonical right meant pointing
--baseat the published url, whichdragged every other url along with it. thefrontside/effection#1248 did exactly
that, and the sitemap went with it — frontside.com mounts a proxied sitemap by
prefixing
/effectiononto every entry, the entries already carried it, and 519urls 404'd:
frontside.com's deploy has been failing since (thefrontside/frontside.com#509 is
the fix on that side). None of that was the intent of #1248; it followed from
--basemeaning two things.Approach
--canonical, defaulting to--base, so every existing invocation behavesexactly as before.
rebase()is then called with one of two targets dependingon what the url is for:
link[rel=canonical]meta[property=og:url]link[rel=alternate]a[href],[src], otherlink[href]llms.txt, feeds, …)A preview can then say what it actually means:
Two calls worth reviewing, both argued in #21:
--canonical.llms.txtis a map telling an agentwhere the docs live rather than a page of the site, and #1248's intent was
that production documents advertise production. The exception is a feed's
rel="self", which should name where the feed is; a blind text substitutioncannot tell the two apart.
--base. It maps this deployment, so a previewdoes not list production urls, and frontside.com's prefixing keeps working as
it always did. Google's guidance that sitemaps list canonical urls argues the
other way.
og:imageandtwitter:imagefollow--base— they point at bytes, and apreview showing its own card seems right. Easy to move if you disagree.
canonicalis optional inStaticalizeOptionstoo, so library callers areunaffected.
Tests
Three new cases, and the existing 30 steps pass untouched — which is the point
of the default.
--canonical, and the rest to--base—asserts canonical/
og:url/alternateland on one, and stylesheet/script/anchor/
og:image/sitemap on the otherllms.txtrewritten to thepublished site, asserting
netlifyappears nowhere--basewhen--canonicalis not given — thecompatibility guarantee
I also ran the real CLI against the Interactors site:
What the consuming sites do next
emits its canonical from the crawl origin
<link rel=canonical>itnever had, then the same flag change
own base option, so staticalize skips it as off-origin. With this, that
plumbing collapses and Effection stops having two different flags named
--base.