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:oneclick@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, what a component variant’s own code does or its content, or an image. Whitespace, comments, shared code, moving a file and renaming the component make none. See Pages, variants and versions.

To see what changed from the version before:

npx routingcat show home/hero:oneclick@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.
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 next dev, add ?rc= to a page’s URL:

?rc=hero:oneclick shows that variant in a slot of the page you open;
?rc=home/hero:oneclick,cta:demo 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. In development, RoutingCat records nothing.

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. Try your first idea shows a full example.

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.
On Hobby, plan counts the site’s live variants toward the 10 your account’s sites share, and marks each variant the deploy would hold.
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, or adding the wrapper route that plan prints.

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.
`next dev`, or a build on your machine	Nothing is registered.

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:

routingcat  LIVE home: 4 variants in hero, routing within about 2 minutes (ch_2, pb_1)
routingcat  NOT LIVE preview: 4 versions registered for home; production unchanged
routingcat  registered ch_1 · objective signup · outcomes trial_started, purchase · no page routed yet

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.

Preview a variant in production

npx routingcat preview home/hero:family

On a home page with three slots:

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.