Try your first idea

In this tutorial you try three new headlines on a home page, beside the current one: you declare them, render them, check what will go live, deploy, and look at each in production. It follows Lumen, whose setup is done. You ask your agent “Try three headlines on the home page”, and it takes these steps with you.

1. Choose the shape

The idea needs one place on one page: a page home with one slot, hero, whose variants are headlines.

The current headline becomes the default, under its own key, current. The control keeps seeing it, 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 the default at the same time, on the same traffic.

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. A headline and a button would be two slots; a redesign would be one slot holding the whole page. See Pages, variants and versions.

2. Declare the page

Each page has its own file in routingcat/:

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

export const home = page('home', {
  routes: ['/'],
  slots: {
    hero: slot({
      default: 'current',
      variants: {
        current: variant({ fields: { headline: 'Edit photos like a pro' } }),
        oneclick: variant({ fields: { headline: 'Pro-level photo edits in one click' } }),
        studio: variant({ fields: { headline: 'Your photos, studio-ready' } }),
        best: variant({ fields: { headline: 'Make every photo your best one' } }),
      },
    }),
  },
})

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

3. Render it

Lumen’s home page is static, so it takes two edits:

The page calls const x = await routingcat.decide(home, { params }) with its own params, and renders the slot through its component, <x.hero>{(f) => <h1>{f.headline}</h1>}</x.hero>. The component lets the browser report which headline each visitor saw.
A wrapper route beside the page serves its prerendered variants:

// The wrapper route of app/page.tsx: it serves the home page's prerendered combinations.
import { routingcat } from 'routingcat/next'
import { home } from '@/routingcat/home'

export * from '../../page'
export { default } from '../../page'
export const generateStaticParams = routingcat.prerender(home)

A server-rendered page calls routingcat.decide(home) instead, and needs no wrapper. Build a page shows both kinds in full.

4. Look at each variant locally

Run next dev and open the home page with ?rc=hero:oneclick at the end of its URL. The page shows that headline until you open it with ?rc=off. In development, RoutingCat records nothing.

5. Check what will go live

npx routingcat plan

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.

limits    4 of 100 variants · 1 of 20 slots · 4 of 1,000 combinations
          the site: 3 live variants, the defaults not counted, of the 10 the Hobby account's sites share
valid     push will accept this                                                   (exit 0)

plan checks your code as the build will, against what production serves, and registers nothing:

each new headline gets a scorecard against current from the moment it goes live;
on Hobby, the line under limits counts 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:

routingcat  LIVE home: 4 variants in hero, routing within about 2 minutes (ch_2, pb_1)

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

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 current. 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 three checks for the page: home live, 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:oneclick

It prints a signed link, valid for one hour, that opens your home page with that headline and a small preview badge. The visit stays out of results, and your own variants stay as they were. 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 headlines 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.