Change, preview and deploy

Every change to what a page offers is a change to its slot markup in your templates. npx routingcat push stamps it, you commit, and your deploy makes it live. Behind a Worker in front of your own server, that takes two deploys: your server’s, which serves the new markup, and the Worker’s, whose build registers it. Your server’s alone registers nothing: until both serve the same templates, a slot whose markup changed shows its default and records no decision, and doctor names it. This guide covers the changes you make most, how to look at a variant on your machine and in production, 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 to the slot, under a key the slot has never used, with hidden; then run npx routingcat push and commit. It goes live at your next production deploy, the Worker’s included where one stands in front of your server, 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 your account’s sites share, 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’s markup under its own key to fix a typo or tighten its wording, then run push, which stamps its new hash, and commit. The edit makes a new version at the next deploy, 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 the variant’s markup changes, as written in the template: Build a page says what counts.

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’s element from the template, run push, and the next production deploy retires it: it stops being served, and its history stays. To remove a slot, keep its default’s content in place of the container; its variants retire. To stop routing a page, remove each of its slots that way, and its entry under pages in routingcat.config.json.
Write 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, since every slot needs one. Remove hidden and data-nosnippet from the new default, so that search engines can quote its text; add hidden to the former default and remove its style="display:contents". Then push completes the markup. Neither variant gets a new version, since a version leaves out what marks the variant that shows.

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

On your machine, run your site’s build, then npx routingcat build, then wrangler dev on Cloudflare Workers, wrangler pages dev on Pages or vercel dev on Vercel, as hugo && npx routingcat build && wrangler dev: RoutingCat’s Worker or middleware runs from what routingcat build writes to .routingcat/. On Workers or Pages, init put routingcat build before Wrangler’s server in your package.json scripts that run it, as npm run preview; in front of your own server, Wrangler’s build command runs it. This build registers nothing, and its pages run in development mode: they show the defaults and record nothing. 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 your templates held at your last routingcat build, deployed or not, so run push and routingcat build again after you add one. A deployed build ignores ?rc=.

Check what a deploy will make live

npx routingcat plan

plan reads your templates and routingcat.config.json, 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, the defaults not counted, 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 declaring under pages a page your markup names.

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. In front of your server, the Worker’s build is the one that registers. On Cloudflare, a build on your machine run with `ROUTINGCAT_ENV=production` registers too, once you confirm its plan: see Deploy from your machine.
Preview: a Vercel preview deployment, or a Cloudflare build of another branch with the preview deploy key	The build registers the new versions and changes nothing live. 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.
A build on your own machine without `ROUTINGCAT_ENV=production`	Nothing is registered, and your pages run in development mode under `wrangler dev` or `vercel dev`: see See a variant in development.

On Cloudflare, a build of another branch registers as a preview only where it carries the preview deploy key, from npx routingcat keys deploy --env preview: the production key proves its own branch alone, so with it, such a build registers nothing. See Cloudflare.

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

routingcat build writes RoutingCat’s first line in the build log. On a production deploy that makes a page live:

$ routingcat build
routingcat  LIVE home: 4 variants in hero, routing within about 2 minutes (ch_01m40j70srer495wr3vhnyvjca, pb_01m40j70srfb59gbvnmr3nv2t6)

On a preview, NOT LIVE takes its place. On Cloudflare, a second line, starting with routingcat:, says which routing data the Worker carries: on a preview, which publishes nothing, the routing data the build started with.

$ routingcat build
routingcat  NOT LIVE preview: 4 versions registered for home; production unchanged
routingcat: this push publishes nothing, as a preview's, so this deployment keeps the exchange's snapshot.

NOT LIVE also appears on a production deploy 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: in the receipt’s place means the build registered nothing, so visitors get your defaults. The deploy ships anyway; the line says what to fix. See Troubleshooting.
Templates push hasn’t stamped, and a head partial other than the one it writes, fail the build, with the message push --check gives, so a deploy never reports other versions, or runs another snippet or tracker, than it registers. An invalid declaration fails it too, with the same message push or plan would have shown:

$ routingcat build
✗ Your templates lack 9 of the edits routingcat push makes, so their slots would report other versions than this deploy registers. Run routingcat push, then commit what it changes.  (D71, exit 1)

$ routingcat build
✗ layouts/partials/routingcat-head.html is not the head partial these templates and routingcat 1.0.0 make. Run routingcat push, then commit it.  (D71, exit 1)

A variant past the 10 live variants your Hobby account’s sites share 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:

https://www.lumen.com/?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 bracketed 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 before its hour is up, as ?rc_preview=off at the end of the page’s address does.