Change, preview and deploy

Every change to what a page offers is a change to its file in routingcat/, and your deploy makes it live. This guide covers the changes you make most, how to look at a variant before and after it goes live, and what each kind of deploy does. To change what is live without a deploy, see Change what’s live.

Try a new idea under a new key

Add a variant under a key its slot has never used. It goes live at your next production deploy, with a scorecard against its slot’s default: both are measured at the same time, on the same traffic. To compare two ideas, give each its own key. On Hobby, past the 10 live variants across your sites, a new variant is held until there is room.

A key stays with its variant for good, even once the variant is retired, so a different idea always takes a new key.

Fix or refine under the same key

Edit a variant under its own key to fix a typo or tighten its wording. The edit makes a new version, such as home/hero:learns@v2, and every version is kept.

Routing builds on what the variant already showed, rather than starting over.
Its scorecard compares the new version with the one it replaced, each over its own period, not at the same time. A different idea under an old key can’t be compared fairly, so it takes a new key.
A version is made only when declared content changes: a field’s value, or an image it references. Whitespace, comments, your pages’ markup, shared code and the slot’s renderer schema make none. See Pages, variants and versions.

To see what changed from the version before:

npx routingcat show home/hero:learns@v2

Remove a variant, or bring one back

Delete a variant from the page’s file, and the next production deploy retires it: it stops being served, and its history stays. Deleting a slot retires its variants; deleting a page also stops routing it. In the same change, put what the slot should show in place of its <RoutingCatSlot>, since a slot the page no longer declares renders nothing.
Declare its key again, and the next production deploy brings it back with its history, and with a new version if its content changed.
Make another variant the default before you delete the default, by changing default: in the slot, because every slot needs one.

retire and resume do the same without a deploy. After either, change the code to match, so the next deploy agrees.

See a variant in development

In astro dev, add ?rc= to a page’s URL:

?rc=hero:learns shows that variant in a slot of the page you open;
?rc=home/hero:learns,subhead:short names the page and several of its slots;
?rc=off returns to the defaults.

The choice lasts for the browser session. It works for any variant declared in your code, deployed or not, and deployed builds ignore it. The development server reads your declarations when it starts, so restart it after adding a page, a slot or a variant. With Astro’s Cloudflare adapter, astro dev runs your Worker, which shows the variants you force; with any other adapter, RoutingCat’s development handler does, in front of your pages. Either way, RoutingCat records nothing in development.

Check what a deploy will make live

npx routingcat plan

plan reads your declarations, checks them as the build will, and compares them with what production serves. It registers nothing.

Each variant has a mark: + new, ~ a new version, - retired.
Each line says what the variant will be compared with: its slot’s default, or its own previous version.
Under limits, each page’s live variants and slots against their limits, and on Hobby the site’s live variants toward the 10 your account’s sites share. A variant the deploy would hold is marked.
plan home reports one page.
Exit code 0 means the build will accept the change. Exit code 1 means it would reject it, and the line says how to fix it, such as declaring an objective.

Your agent runs plan and tells you what will go live before you deploy.

Know what each deploy makes live

Deploy	What happens
Production	The build registers the change, and it is live within about 2 minutes.
Preview	The build registers the new versions and changes nothing live. The preview deployment’s visitors are routed as production’s are, between production’s live variants: a page, slot or variant only the preview declares shows its default, and stays a draft until a production deploy declares it. Their visits and events stay out of your results.
`astro dev`, or a build on your machine without `ROUTINGCAT_ENV=production`	Nothing is registered.

What counts as production depends on the host:

On Vercel, your production deployments are production, and every other deployment is a preview, as Vercel’s own token tells RoutingCat.
On Cloudflare Workers, a build registers with the deploy key in its variables. The production key, npx routingcat keys deploy --branch <your production branch>, registers builds of that branch alone; the preview key, npx routingcat keys deploy --env preview, registers previews. astro build registers the change, then wrangler deploy deploys the Worker. On your machine, astro build run with ROUTINGCAT_ENV=production registers production under your sign-in, once you confirm its plan: see Deploy from your machine.

A production deploy applies only what its code changed since the previous one, so an act on something the code didn’t change holds.

The first line RoutingCat writes in the build log says which happened. It is one of these:

The line starts	It means
`routingcat LIVE`	A production deploy that routes a page, live within about 2 minutes. The line counts each slot’s live variants.
`routingcat NOT LIVE preview:`	A preview: its new versions are registered, and production is unchanged.
`routingcat registered`	A production deploy with no page routed yet. The line names your objective and outcomes.

NOT LIVE also appears on a production build when routing is off for the site, or when the build isn’t allowed to publish. On Hobby, until the site’s owner has a card on file, it reads routingcat NOT LIVE routing waits for a card on file: add one at …, nothing charged: see Add a card to start routing.
A line starting with routingcat: instead means the build registered nothing, so visitors get your defaults. The build ships anyway; the line says what to fix. See Troubleshooting.
Only an invalid declaration fails the build, with the same message plan would have shown. A variant past Hobby’s 10 live variants is held instead, and the build log names it after its first line, with the held-variants warning. On Vercel, a build whose adapter runs Astro’s middleware at the edge passes too, and its log warns that RoutingCat routes none of the pages rendered at request time.
On Vercel, the build registers before Astro prerenders your pages, so a build that fails while prerendering has registered already: visitors keep the previous version, and status says so. Fix the build and deploy again, or revert the page.

Preview a variant in production

npx routingcat preview home/hero:family

On a home page with three slots, it prints:

https://pantry.app/?rc_preview=1.eyJraWQiOiJwdmtfOTU2NGMzZjA5MTlkYWY0YyIsInNpdGUiOiJzdF8wMWt4MGY5Nm0wZm0ycjFjZGUzMHhycW4xYSIsImVudiI6InByb2R1Y3Rpb24iLCJleHAiOjE3OTIwNTcyMDAsImJ5IjoicHJfMDFtMmozajVyMGUwanJjOHNteHNmM3oxajYiLCJ4IjpbImhvbWUvaGVybzpmYW1pbHkiLCJob21lL2N0YTpzdGFydC1mcmVlIiwiaG9tZS9pbWFnZTpraXRjaGVuIl19.Zml4dHVyZS1zaWduYXR1cmU
  forces home/hero:family@v1 · defaults elsewhere: home/cta:start-free@v1, home/image:kitchen@v1
  path / (its first route) · on dp_01m4xeq560edfb3k7r2f65mexw · until 09:40Z
Opened in a browser, it shows a preview badge; the visit stays out of results and leaves your own assignments as they are.

The link is signed and valid for one hour. It shows the variants you name, at most one per slot of one page, and the defaults in the page’s other slots.
It opens the page’s first route without a dynamic segment, else its most frequent path over the past 7 days. Give --path /pricing when the page has neither.
The production deployment must carry the version. Right after a deploy, preview loads your site once, so the new deployment registers, then asks again.
The badge names the variant each slot shows, read from the page itself, so a preview that couldn’t show its variant says so. Its link ends the preview.