Try your first idea

In this tutorial you try new headlines on a home page, beside the current one, and a shorter version of the line under them: you declare them, render them, check what will go live, deploy, and look at each in production. Your setup is done. You ask your agent “Try two new headlines on the home page, and a shorter line under them”, and it takes these steps with you. The code comes from an example Astro site, a landing page whose main conversion is joining its waitlist.

1. Choose the shape

The idea needs two places on one page: a page home with two slots, hero, whose variants are headlines, and subhead, the line under it.

The current headline and line become the defaults, each under its own key, current. The control keeps seeing them, so the measured gain compares routing with what your site shows today.
Each new idea gets a new key, so that it is compared with its slot’s default at the same time, on the same traffic.
Slots vary independently, so any headline can show above any line: 3 headlines and 2 lines make 6 combinations, and each must read well. Pieces that must match go in one slot instead.

Your agent writes the headlines from what your site already says. A claim, such as a number, a testimonial or a price, must be true, so it comes from your site or from you. See Pages, variants and versions.

2. Declare the page

Each page has its own file in routingcat/, which imports page, slot and variant from routingcat/astro:

import { page, slot, variant } from 'routingcat/astro'

export const home = page('home', {
  routes: ['/'],
  slots: {
    hero: slot({
      default: 'current',
      variants: {
        current: variant({ fields: { headline: 'Route every visitor to what converts' } }),
        learns: variant({ fields: { headline: 'Your pages learn what converts each visitor' } }),
        shows: variant({ fields: { headline: 'Show each visitor the page that converts them' } }),
      },
    }),
    subhead: slot({
      default: 'current',
      variants: {
        current: variant({
          fields: {
            text: 'Each visitor sees the version of the page most likely to convert them, and you see which version works for whom.',
          },
        }),
        short: variant({
          fields: { text: 'Every visitor gets the page that works for them. You see what works.' },
        }),
      },
    }),
  },
})

An address names each variant, as home/hero:learns, in commands and on the dashboard.

3. Render it

The page renders each slot in a <RoutingCatSlot>, whose child is a function of the variant’s fields. The home page, src/pages/index.astro:

---
// `/`, prerendered: every variant in the page, the head snippet showing the host's selection.
import { RoutingCatSlot } from 'routingcat/astro/components'
import { home } from '../../routingcat/home'
import Base from '../layouts/Base.astro'
---
<Base title="RoutingCat">
  <main>
    <RoutingCatSlot page={home} name="hero">
      {(fields: { headline: string }) => <h1>{fields.headline}</h1>}
    </RoutingCatSlot>
    <RoutingCatSlot page={home} name="subhead">
      {(fields: { text: string }) => <p>{fields.text}</p>}
    </RoutingCatSlot>
    <a href="/pricing">See pricing</a>
  </main>
</Base>

The page is prerendered, as Astro pages are unless they opt out, so its HTML carries every variant: the defaults show, the others are hidden, and <RoutingCat />, which init put in your layout’s <head>, shows each visitor’s own variants before the page paints. The slot component also lets the browser report which variants each visitor saw. A page rendered at each request takes the same edit, and carries its visitor’s variants alone; Build a page shows both kinds.

4. Look at each variant locally

Run astro dev and open the home page with ?rc=hero:learns at the end of its URL. The page shows that headline until you open it with ?rc=off. The development server reads your declarations when it starts, so restart it after adding a variant. In development, RoutingCat records nothing.

5. Check what will go live

npx routingcat plan

plan checks your code as the build will, against what production serves, and registers nothing. It lists the page, each slot with its default, and each variant with the start of its text:

+ marks each new variant, and each new headline gets a scorecard against current from the moment it goes live;
under limits, it counts the page’s live variants against 100 and its slots against 20, and on Hobby the site’s live variants, the defaults not counted, toward the 10 your account’s sites share: past them, a new variant is held rather than served, and plan marks it;
exit code 0 means the build will accept the page; 1 means it would reject it, and the line says what to fix.

Your agent tells you what will go live, in plain words, before you deploy.

6. Deploy

Commit and deploy to production. The build log confirms it, with a line that starts routingcat LIVE home: and counts each slot’s variants.

This deploy changes what visitors see. Within about 2 minutes, 90% of your visitors are routed between the headlines and between the lines under them; the control keeps seeing current in both slots. A preview deployment would only register them.

On Hobby, routing waits for a card on file. Until the site’s owner adds one, the line reads routingcat NOT LIVE routing waits for a card on file: add one at …, nothing charged, and the page keeps serving its defaults. Routing starts within about 2 minutes of the card, with no new deploy: see Add a card to start routing.

npx routingcat doctor --wait now adds four checks for the page: home live, selection, first decision and first render beacon. The last arrives once a browser shows the page.

7. See a variant in production

npx routingcat preview home/hero:learns

It prints a signed link, valid for one hour, that opens your home page with that headline, the line under it at its default. The page shows a badge naming the variant each slot shows. The visit stays out of results, and your own variants stay as they were. The badge’s link ends the preview before the hour is up. See Change, preview and deploy.

8. Watch the first days

Routing learns once a day on Hobby, and on Pro as conversions mature, at most hourly, from visits whose window has closed. With the 24-hour window, a visit starts to shape routing a day or two later on Hobby, about a day later on Pro.
New variants start cautiously, at signal New, with a limited share of visits until evidence builds. A small random slice of visits is always split evenly.
The measured gain starts wide. It shows no range while visits are few, then a range; while that range spans zero, the direction isn’t known yet.
Wait for the evidence. Checking every day and acting on the first good day overstates gains.

Ask your agent “How is it going?”: it runs npx routingcat status and says each number with how sure it is. See Read and explain results. The page’s screen on your dashboard shows the same figures: see Read the dashboard. Once one headline is clearly ahead, promoting it makes it the default; see Change what’s live.