Getting started

Switches keeps several versions of a page section on your real site. A round button at the bottom left opens a panel where anyone can flip between them, pick one per section and copy the picks as text for Claude Code. Setup is three steps.

1. Install

In your project folder, run:

pnpm add switches-react && npx switches init

The first command adds the package (with npm: npm i switches-react; with yarn: yarn add switches-react). The second sets up Claude Code: it writes a skill to .claude/skills/switches/SKILL.md and adds a short Switches block to CLAUDE.md. Run npx switches only after installing switches-react; the bare name switches on npm is an unrelated package.

init takes an optional version-first mode, which decides whether Claude Code offers versions on its own when it builds something new:

npx switches init [--mode off|ask|always]

• off: one version, unless you ask for more.
• ask (the default): before building a new section or page layout, Claude asks “want 3 versions?”
• always: Claude builds 2 or 3 versions of each new section or layout without asking.

Small edits, fixes and copy changes always stay one version. Run init again to change the mode.

2. Add the panel

Render <Switches /> once, as the very first thing inside <body>. It includes a tiny script that applies saved picks before the page first paints, so it has to come before your content.

Next.js App Router

In app/layout.tsx. Also add suppressHydrationWarning to <html>: the script sets a data-switches-picks attribute there before React loads, which React would otherwise report as a hydration mismatch in development.

import { Switches } from "switches-react";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Switches />
        {children}
      </body>
    </html>
  );
}

Next.js Pages Router

In pages/_app.tsx, as the first element, before the page. Not in _document: that file only renders on the server, so the panel would never start. No suppressHydrationWarning is needed here. Tested with Next.js 14 and React 18.3.

import type { AppProps } from "next/app";
import { Switches } from "switches-react";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Switches />
      <Component {...pageProps} />
    </>
  );
}

Plain React (Vite and similar)

As the first element of your root component. Without server-rendered HTML, picks apply when React renders, so a page opened with a pick can briefly show the default version first. The NEXT_PUBLIC_SWITCHES=off flag works only if your bundler replaces process.env.NEXT_PUBLIC_SWITCHES; otherwise Switches is simply on.

3. Wrap the versions

Each version of a section goes in a <Variant> with the same name and its own option. Put them next to each other. Usually you don’t write this by hand: ask Claude Code for versions and it writes this for you.

import { Variant } from "switches-react";

<Variant name="hero" option="original" default>
  <HeroOriginal />
</Variant>
<Variant name="hero" option="phone">
  <HeroPhone />
</Variant>
<Variant name="hero" option="split">
  <HeroSplit />
</Variant>

Open the page, press the round button at the bottom left, and the Hero section is there with three choices. Deploy it as usual and send the preview link to whoever is choosing.

Next: what the panel can do, in Features. Before you launch, read how to finish.