⌘K
GitHub

Docs

Getting Started

Set up kalp in an existing React project and make your first visual edit. This takes about five minutes.

Requirements

Before you install kalp, make sure you have:

  • React 18 or newer. kalp is a React component, and React is a peer dependency — your app provides it.
  • Node.js. The bridge server is a small Node program; any recent Node version that runs your dev server will run kalp.
  • Claude Code, installed and logged in. This is the important one. kalp does not talk to any AI service itself — it hands your edits to the Claude Code CLI on your machine, and Claude Code edits the files. Without it, the editor still works for previewing, but "apply to code" will fail.

To set up Claude Code:

# install the CLI
npm install -g @anthropic-ai/claude-code

# open it once and log in
claude
# then type /login and follow the prompts

If you use an API key instead of a login, setting the ANTHROPIC_API_KEY environment variable also works — kalp accepts any credential setup that Claude Code itself accepts.

kalp checks for Claude Code when the bridge server starts and again before every apply. If something is missing you get a plain-language error in your terminal and in the editor panel — see Troubleshooting.

1. Install the package

npm install @deval2498/kalp

One package contains both pieces: the <Kalp /> React component and the kalp command.

2. Add the component

Render <Kalp /> anywhere in your app — the root is the usual place. It renders nothing except its own floating UI, so it does not affect your layout.

import { Kalp } from "@deval2498/kalp";

function App() {
  return (
    <>
      {/* your app */}
      {process.env.NODE_ENV === "development" && <Kalp />}
    </>
  );
}

The NODE_ENV guard keeps kalp out of your production build. kalp is a development tool — there is no reason to ship it to users.

3. Run the bridge server

The browser cannot edit files on your disk, so kalp runs a tiny local server that can. Start it from your project root (the folder with your source code), alongside your normal dev server:

// package.json
"scripts": {
  "dev": "kalp & vite"      // Vite
  // or: "kalp & next dev"  // Next.js
}

You will see this in your terminal when it starts:

[kalp] bridge server running on http://localhost:3001
[kalp] watching for prompts from <Kalp /> component...
[kalp] cwd: /path/to/your/project

The component finds the server on its own — no configuration, no URL to paste. If port 3001 is busy, the server picks the next free port (up to 3010) and the component still finds it. You can also pick a port yourself with kalp --port 4000. Details are in the CLI reference.

Using with Next.js

<Kalp /> uses browser APIs, so in the App Router it must live in a Client Component. Make a small wrapper:

app/kalp-dev.tsx
"use client";
import { Kalp } from "@deval2498/kalp";

export default function KalpDev() {
  return <Kalp />;
}

Then render it in your root layout, development only:

app/layout.tsx
import KalpDev from "./kalp-dev";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        {process.env.NODE_ENV === "development" && <KalpDev />}
      </body>
    </html>
  );
}

And run the bridge next to Next: "dev": "kalp & next dev".

4. Your first edit

Open your app in the browser. You will see a round paintbrush button in the bottom-right corner.

  1. Click the paintbrush. The cursor becomes a crosshair and elements highlight as you move over them, labeled with their React component name.
  2. Click an element. The editor panel opens on the right with that element's current styles loaded.
  3. Change something. Drag the Corner Radius row, pick a new background color — every change previews on the page instantly. Changed rows turn blue so you can see what you touched.
  4. Click "apply to code". kalp sends your edits to the bridge server, which asks Claude Code to write them into the component's source file using your project's own styling approach. When it finishes, the preview styles are removed and your dev server hot-reloads with the real change.

That's the whole loop. The Visual Editor guide covers everything else the panel can do — multi-select, the Layout tab, per-property undo, and the free-form prompt box.

← Home How It Works →