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, on Vercel or on Cloudflare. 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 a variant’s fields change. Whitespace, comments, the page’s template, 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.
Declare its key again, and the next production deploy brings it back with its history, and with a new version if its fields 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 nuxt 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, in-page navigations included. It works for any variant your code declared when nuxt dev started, deployed or not, so restart it after you add a variant. Open your pages at localhost: over plain HTTP at another address, they show their defaults. Deployed builds ignore ?rc=. In development, RoutingCat records nothing.

Check what a deploy will make live

npx routingcat plan

For Lumen’s home page, declared for the first time with four headlines:

lumen · this code against production (dp_01m3yfqdsgfkr9jahvnyvk6gaa, commit 4be1c07) · contract 1.0

home  new page · route / · objective signup, 24 h (from routingcat.config.ts)
  hero  new slot · default current
    + current   "Edit photos like a pro"                  the default, which the control always sees
    + oneclick  "Pro-level photo edits in one click"      scorecard against current
    + studio    "Your photos, studio-ready"               scorecard against current
    + best      "Make every photo your best one"          scorecard against current

In production this goes LIVE, with routing within about 2 minutes:
  the control keeps seeing the defaults · the random slice of visits is split evenly
  the rest are routed toward signup, as the model learns which variant works for whom
A production deploy applies only what its code changed since the previous production deploy.
A preview deployment registers these versions and changes nothing live.
…
valid     push will accept this                                                   (exit 0)

plan reads your declarations, checks them as the build will, and compares them with what production serves. It registers nothing. Try your first idea walks through it.

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.

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. On Vercel, a production deployment; on Cloudflare, a build of your production branch, with the production deploy key, or a build on your machine run with `ROUTINGCAT_ENV=production`, once you confirm its plan: see Deploy from your machine.
Preview	The build registers the new versions and changes nothing live: on Vercel, a preview deployment; on Cloudflare, a build with the preview deploy key, from `npx routingcat keys deploy --env preview`. The preview’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.
`nuxt dev`, or a build on your machine without `ROUTINGCAT_ENV=production`	Nothing is registered.

On Cloudflare, a build of another branch with the production deploy key registers nothing, and its log says why.

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, among nuxt build’s, 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_01m3yfrpt0fbttmb64x6008p1n · objective signup · outcomes waitlist · 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:oneclick

On a home page with one slot, it prints a signed link that opens the page with the variants you name, in production:

https://lumen.so/?rc_preview=1.eyJieSI6InByXzAxazZnIn0.c2ln
  forces home/hero:oneclick@v2
  path / (its first route) · on dp_01m4xns9ggfyhra1beeb6f424r · until 10:12Z
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.