Getting started with Popmelt Core
Add Popmelt to your local app and make your first change on the page.
Open the Popmelt toolbar, click an element in your running app, ask your agent to change it, and review the result in your browser. You can reply right beside the button to refine the change.
What you need
- A web app you can already run on your computer. React is the established integration. Other supported frameworks can use experimental integrations to comment on and style page elements.
- Node.js 18 or newer. If your app's framework requires a newer version, use that version.
- A Codex or Claude Code account. Your agent can install its CLI during setup and guide you through signing in.
You can open your app in a regular browser or in your coding agent’s built-in browser. In either case, the command-line version of your agent (CLI) runs the conversations on the page. You can use Core locally without a Popmelt cloud account.
Install with your agent
Open your project in Codex or Claude Code and paste this prompt.
Install @popmelt.com/core in this project. Set up the matching CLI for the agent I'm using (Codex or Claude Code) in the environment that runs my dev server. If it's missing, install it using the vendor's setup instructions. If it needs sign-in, guide me through login and verify it afterward. Verify the Popmelt bridge and tell me which local URL to open.
When your agent finishes setup, open the local address it gives you. If you’re starting the app yourself, use your usual development command, such as npm run dev.
For manual setup, use the React instructions or the other framework instructions.
Make your first change
- Open Popmelt. Double-tap Command on macOS or Control on Windows or Linux. You should see the Popmelt toolbar. If it’s missing, check your setup.
- Write a note. Choose Chat (the speech bubble) from the tool menu, or press
C. Click a button in your app and type what you’d like to change. For example, try “Give this button a clearer label.” - Send your note. Press Enter to save the draft, then click Send beside the note to start the agent. You can also send with Command+Enter or Control+Enter.
- Review the change. When the agent replies, check the result on the page. To refine it, click the reply badge, type a follow-up, and press Enter.
Manual React setup
Install Core in your React project.
npm install @popmelt.com/core
Use React 18 or newer and wrap your app in PopmeltProvider. If your app has multiple routes, pass your router's navigation function so threads can reopen on the right page.
Next.js
With the Next.js App Router, put the provider in a client component.
'use client';
import type { ReactNode } from 'react';
import { useRouter } from 'next/navigation';
import { PopmeltProvider } from '@popmelt.com/core';
export function Providers({ children }: { children: ReactNode }) {
const router = useRouter();
return <PopmeltProvider navigate={router.push}>{children}</PopmeltProvider>;
}
Render <Providers>{children}</Providers> in your root layout. Wrap your existing Next config with withPopmelt, keeping its settings.
import { withPopmelt } from '@popmelt.com/core/next';
const nextConfig = {};
export default withPopmelt(nextConfig);
Add popmelt wrap -- before your development command, keeping any existing flags.
{
"scripts": {
"dev": "popmelt wrap -- next dev"
}
}
The command starts the local bridge, and the config connects the browser to it. Next.js needs both.
Vite with React
In your React entry file, often src/main.tsx, wrap your app with PopmeltProvider. Keep any existing wrappers around the app.
import { PopmeltProvider } from '@popmelt.com/core';
import { createRoot } from 'react-dom/client';
import App from './App';
createRoot(document.getElementById('root')!).render(
<PopmeltProvider>
<App />
</PopmeltProvider>,
);
Add popmelt() to your 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()],
});
Experimental framework setup
Vanilla Vite, Vue, Svelte/SvelteKit, Nuxt, and Astro support DOM annotations and style edits. Popmelt uses React internally to render its toolbar. Install the renderer dependencies alongside Core in the host project.
npm install -D @popmelt.com/core react react-dom
Vanilla Vite and Vue
Add popmelt() from @popmelt.com/core/vite to your existing Vite plugins. Mount the toolbar in the browser entry after mounting your app.
if (import.meta.env.DEV) {
const { mountPopmelt } = await import('@popmelt.com/core/browser');
const toolbar = await mountPopmelt({ enabled: true });
import.meta.hot?.dispose(() => toolbar.unmount());
}
In Vue 3.5+, register app.onUnmount(() => toolbar.unmount()) for application teardown. If you use Vue Router, pass navigate: (url) => router.push(url) in the mount options so threads can reopen on the right route.
Svelte and SvelteKit
Add the same popmelt() Vite plugin alongside svelte() or sveltekit(). Mount once in your root +layout.svelte, keeping its existing content.
<script>
import { onMount } from 'svelte';
import { goto } from '$app/navigation';
import { bridgeUrl, projectId } from 'virtual:popmelt/bridge';
onMount(() => {
if (!import.meta.env.DEV || !bridgeUrl || !projectId) return;
let disposed = false;
const pending = import('@popmelt.com/core/browser').then(({ mountPopmelt }) => {
if (!disposed) return mountPopmelt({ enabled: true, bridgeUrl, projectId, navigate: goto });
}).catch(console.error);
return () => {
disposed = true;
void pending.then((toolbar) => toolbar?.unmount());
};
});
</script>
For plain Svelte, use App.svelte and omit the goto import and navigate option. For virtual module types, add /// <reference types="@popmelt.com/core/vite/client" /> to the app's ambient declarations.
Nuxt and Astro
In Nuxt 4.5.2 or later in the 4.x series, add the module to your existing config.
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@popmelt.com/core/nuxt'],
});
In Astro, add the integration to your existing config.
// astro.config.mjs
import { popmelt } from '@popmelt.com/core/astro';
import { defineConfig } from 'astro/config';
export default defineConfig({ integrations: [popmelt()] });
Both integrations start the bridge and mount the toolbar automatically in development.
Verify your agent
After wiring up your framework, make sure the agent you want to use is installed and signed in in the same environment that starts your dev server.
| Agent | Check sign-in | Sign in |
|---|---|---|
| Codex | codex login status | codex login |
| Claude Code | claude auth status | claude auth login |
If you're an agent setting up Popmelt, use the user's chosen CLI. If it is missing, install it using the provider's official instructions, then ask the user to complete any interactive sign-in. Recheck sign-in and verify the app's Popmelt bridge before reporting setup complete. Codex CLI setup · Claude Code setup
If something is missing
- No toolbar. Check that your framework setup mounts
PopmeltProvideror the standalone toolbar. In Next.js, check both the config and the development command. - Bridge disconnected. The bridge is the local process that connects your app to your coding agent. Check that your project's bridge is running and that the toolbar connects to it.
- Agent unavailable. Check that the matching CLI is installed, its version is compatible, and it can run with your credentials in the terminal you used to start your app.
If a note stays on Sending, recover the annotation and check whether it reached the thread. For details about what gets stored or reported, see Where Popmelt saves and sends your data.
Next: Creating annotations with the Chat tool, Tweaking styles with the Steer tool, or Helping your AI understand your taste with the Imprint tool.
Didn't find the answer? Have an idea?
Ask a question