Getting started with Popmelt Core

Core turns your local web app into a design sandbox. Point to an element, describe a change, or preview it directly, then work through the result with your coding agent in a thread on the page.

What you need

• A local web project. React is the established integration; other supported frameworks have experimental DOM integrations.
• Node.js 18 or newer, or a newer version required by your framework.
• The Codex CLI or Claude Code CLI installed, available in your terminal, and signed in.

You can use a regular browser or a coding agent's built-in browser. The corresponding CLI still runs the in-page threads, even when you use a desktop app. Core's local workflow does not require a Popmelt cloud account.

Install with your agent

From your project, ask:

Let's install @popmelt.com/core in this project

Your agent should add the integration for your framework, preserve the existing development command, and check the toolbar, bridge connection, and provider sign-in. Restart the intended development server after setup, once any active work has finished.

Manual React setup

Install Core and its icon peer dependency in an existing React project:

npm install @popmelt.com/core lucide-react

Wrap the app in PopmeltProvider. React hosts require React 18 or newer. For routed apps, pass your router's navigation function so threads can reopen on the right page.

In Next.js, the provider component must be a client component:

'use client';

import { useRouter } from 'next/navigation';

import { PopmeltProvider } from '@popmelt.com/core';

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  return <PopmeltProvider navigate={router.push}>{children}</PopmeltProvider>;
}

Render Providers around your app's children in the root layout. Defining the component alone does not mount Core.

Next.js

Wrap the existing Next config, preserving its settings:

import { withPopmelt } from '@popmelt.com/core/next';

const nextConfig = {};
export default withPopmelt(nextConfig);

Also wrap the development command, preserving any flags it already uses:

{
  "scripts": {
    "dev": "popmelt wrap -- next dev"
  }
}

Both wrappers are required: the command starts the project bridge, and the config connects the browser to it.

Vite with React

Keep the provider and add Popmelt to the existing Vite plugins:

import { popmelt } from '@popmelt.com/core/vite';
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [react(), popmelt()],
});

Vanilla HTML/JS with Vite, Vue, Nuxt, Svelte/SvelteKit, and Astro have experimental integrations. They support DOM annotations and style edits, not React-specific component hierarchy or library previews. Use the framework-specific instructions in the Core README rather than adding a React provider to a non-React app.

Make your first change

1. Start your app with its normal development command and open its local URL.
2. Double-tap Command on macOS or Control on Windows/Linux to open the toolbar.
3. Choose Chat (C), click an element, and describe one concrete change.
4. Press Command/Control+Enter to send the pending work.
5. Review the result on the page and refine it in the same thread.

Try: “Give this card more breathing room without changing the text size.”

If something is missing

• No toolbar: check the provider or browser mount and the framework integration. Next.js needs both wrappers.
• Bridge disconnected: check that this project's bridge is running and that the toolbar points to it.
• Agent unavailable: check the matching CLI, its version, sign-in, and the environment the bridge runs in.

Check for active work before restarting a process. A healthy bridge does not by itself prove the browser is connected or the agent is signed in.

Next: Creating annotations with the Chat tool, Tweaking styles with the Steer tool, or Helping your AI understand your taste with the Imprint tool.