routingcat

routingcat

RoutingCat routes each visitor of your site to the variants that convert, and learns continuously from outcomes, such as sign-ups and purchases. It shows what is working, measured against a share of visitors who keep your defaults.

Install

In your site's folder:

npx routingcat init

init reads your framework and host, signs you in, creates your site, and makes the edits, this package and the skill for your coding agent among them. Nothing reaches visitors until you deploy. The documentation, at https://docs.routingcat.com, takes it from there for your kind of site.

Versions

Any later version works, a later major included: nothing refuses it. Where your build runs a newer major than RoutingCat was tested with, it prints one line saying so, and npx routingcat doctor shows it too, so that you know where to look first if something seems off.

What's inside, by kind of site

Each kind of site has its own copy of the documentation, at the address below, and in node_modules/routingcat/docs/ for the version you have.

• Next.js on Vercel, https://docs.routingcat.com/nextjs/: routingcat/next, to declare what varies, decide, render and track, and routingcat/next/proxy, for proxy.ts.
• Nuxt on Vercel or Cloudflare, https://docs.routingcat.com/nuxt/: routingcat/nuxt, the module; routingcat/vue, its components and calls; and the host's entry, from routingcat/vercel or routingcat/cloudflare, which init writes.
• Astro on Vercel or Cloudflare, https://docs.routingcat.com/astro/: routingcat/astro, the integration; routingcat/astro/components; routingcat/tracker, for a page's own script; and the host's entry, from routingcat/vercel or routingcat/cloudflare, which init writes.
• A static or server-rendered site on Vercel or Cloudflare, https://docs.routingcat.com/html/: the host's entry, from routingcat/vercel or routingcat/cloudflare, which init writes, and the script of routingcat/tracker, which its pages load.
• Any other website, https://docs.routingcat.com/script/: the head partial npx routingcat push writes, which runs RoutingCat in the page, and routingcat/runtime, for an app that bundles it.
• Every kind: routingcat/browser, the calls of a page RoutingCat doesn't render, also as a script tag; routingcat/outcomes, the payment providers' events for a webhook handler of your own; the routingcat command, which npx routingcat --help lists; the skill, which init installs for your coding agent; and the JSON Schema of every command's --json output, in schemas/.

The scripts, from the CDN

A page can load either script without a bundler, from an address that never changes for a version, with its Subresource Integrity:

• routingcat/browser's, whose calls go on the page's window.routingcat:

  <script src="https://cdn.routingcat.com/browser/1.0.0.js" integrity="sha384-ZnRbP0Groc12kRo2DHm+EpSi/r27mWVkwT7ehqGhXHZY3NjqdZvTJHtolZL8IbFW" crossorigin="anonymous" data-key="pk_…"></script>
  

• the tracker, routingcat/tracker's, after the head snippet, on a site whose host decides:

  <script src="https://cdn.routingcat.com/tracker/1.0.0.js" integrity="sha384-/b5CIohNEzIZNIoo2yIgbhEsJBjhizr2sdr/mxXZbDLDfDsBMseg6/xo2gNhm1YW" crossorigin="anonymous" defer data-key="pk_…"></script>
  

Stability

The routingcat package follows semantic versioning for what this section lists: within 1.x, a minor or patch version only adds to it, and never removes or changes what it names. A change to any of it waits for 2.0.

• The stable entries, each with the names it exports, values and types:
  • routingcat/next: config, ConfigDeclaration, Decided, DeclarationError, fromMinorUnits, IdentifyOptions, page, PageDeclaration, RoutingCat, routingcat, routingcatProperties, slot, SlotDeclaration, SlotResult, TrackOptions, variant, VariantDeclaration and withRoutingCat.
  • routingcat/next/proxy: proxy, ProxyHandler and ProxyOptions.
  • routingcat/browser: IdentifyOptions, InitOptions, LineItem, routingcat, routingcatProperties and TrackOptions.
  • routingcat/tracker: navigate, prepareNavigation, routingcat, routingcatProperties, start and StartOptions.
  • routingcat/outcomes: AccountOrigin, AccountSource, Ask, CancelEffectiveProperties, CancelScheduledProperties, currencyExponent, CustomerType, DEFAULT_LINK, DisputeProperties, DisputeState, Dropped, DropReason, Env, EveryOutcome, fromMinorUnits, GetRead, Item, JsonValue, LinkConfig, LinkOut, ListRead, MapContext, Mapped, Mapping, Mode, MoneyOutcome, Need, needKey, Outcome, OutcomeName, OutcomeOfName, PaymentProperties, PriorOutcome, Projected, Projection, Provider, PurchaseProperties, Read, ReadRecord, ReadResult, Reads, readsOf, RefundProperties, RenewalProperties, run, RunResult, shopify, SHOPIFY_API_VERSION, SHOPIFY_API_VERSIONS, SHOPIFY_TYPES, ShopifyDelivery, shopifyKey, ShopifyKeyInput, ShopifyOrderProperties, shopifyTrigger, stripe, STRIPE_API_VERSION, STRIPE_API_VERSIONS, STRIPE_TYPES, stripeKey, StripeKeyInput, stripeReadPath, stripeTrigger, TrialStartedProperties, Trigger, ValueBasis, versioned, VisitorLink, whop, WHOP_API_VERSION, WHOP_API_VERSIONS, WHOP_TYPES, WhopDisputeState, whopKey, WhopKeyInput and whopTrigger.
  • routingcat/vercel: ASTRO_DESCRIPTOR, FrameworkDescriptor, HTML_DESCRIPTOR, middleware, MiddlewareContext, MiddlewareHandler, MiddlewareOptions, NUXT_DESCRIPTOR and RoutingCatBuild.
  • routingcat/cloudflare: ASTRO_DESCRIPTOR, CloudflareOptions, CloudflareWorker, FrameworkDescriptor, HTML_DESCRIPTOR, NUXT_DESCRIPTOR, pages, PagesContext, PagesOptions, RoutingCatBuild, worker, WorkerContext and WorkerOptions.
  • routingcat/vue: config, ConfigDeclaration, DeclarationError, IdentifyOptions, page, PageDeclaration, routingcat, routingcatProperties, RoutingCatSlot, RoutingCatSlotProps, RoutingCatSlotScope, RoutingCatState, ServerEvent, Shown, slot, SlotDeclaration, TrackOptions, useRoutingCat, variant and VariantDeclaration.
  • routingcat/nuxt: default and RoutingCatNuxtOptions.
  • routingcat/astro: config, ConfigDeclaration, DeclarationError, default, IdentifyOptions, page, PageDeclaration, RoutingCatAstroOptions, RoutingCatLocals, Shown, slot, SlotDeclaration, TrackOptions, variant and VariantDeclaration.
  • routingcat/astro/components: RoutingCat, RoutingCatProps, RoutingCatSlot and RoutingCatSlotProps.
  • routingcat/runtime: CORE_VERSION, CoreAttributes, CoreConfig, RcState, RoutingCatPage, runCore, runPost and ViewState.
• The files the package exports beside them, at their paths and in their formats:
  • routingcat/runtime/core.js: the browser runtime's core, which a head partial carries inline.
  • routingcat/runtime/post.js: its post part, which a head partial loads from cdn.routingcat.com.
  • routingcat/runtime/manifest.json: their versions, hashes and sizes, format rc.runtime/1.
  • routingcat/schemas/*: the JSON Schema of each command's output, a failure and the config.
• The experimental entries, routingcat/react-router, routingcat/fetch, routingcat/react and routingcat/vite, are outside the promise, each as a whole: any version may change them, a patch included, until RoutingCat supports Hydrogen storefronts. Their declarations say @experimental, and a name they share with a stable entry, as the declarations, is stable through that entry alone.
• The environment variables you may set, every other one starting with ROUTINGCAT_ being RoutingCat's own, for its tests, which may change:
  • ROUTINGCAT_DEPLOY_KEY: a build's credential where no Vercel or GitHub Actions OIDC token proves it, from npx routingcat keys deploy.
  • ROUTINGCAT_BRANCH: the branch a CI RoutingCat does not recognize builds.
  • ROUTINGCAT_ENV: set to production, a production build on your own machine, for a site on Cloudflare.
  • ROUTINGCAT_CONFIRM: the digest a production build's plan printed, which confirms that plan on the next run.
  • ROUTINGCAT_CONFIG_DIR: the folder where the command keeps its sign-in when it does not use the keychain.
  • ROUTINGCAT_KEYCHAIN: set to off, the command keeps its sign-in in that folder, never the keychain.
• Messages keep their id, as D2, and their code, as next_insecure: neither is ever reused for another message, and a code's parameters keep their names and meaning. Their words may change, so read the id and the code, never the text (Messages).
• The JSON contract: every --json output states contract, 1.0. Within version 1 it only grows: new fields, and new values where a field's values are listed, never one removed, renamed or retyped. The JSON Schema of each command's output and of a failure ships in node_modules/routingcat/schemas/, which schemas/index.json lists with the package's and the contract's versions (JSON output).
• Exit codes, and no other (the command):
  • 0: done.
  • 1: rejected, denied or failed, with a message id.
  • 2: the command or its arguments are wrong.
  • 3: waiting, on a person or on time: run the same command again later.
  • 4: RoutingCat can't be reached.

License

MIT