Installation

Get Clickly running in your React project in under two minutes.

Requirements

  • React 17 or later
  • Node.js 16 or later
  • Works with Next.js, Vite, Create React App, Remix, and any other React framework
  • Automatically tree-shaken in production builds — zero runtime overhead when NODE_ENV !== "development"

Install the package

npm install useclickly

Basic usage

Import Clickly and render it anywhere in your component tree. We recommend wrapping it in a dev-only guard so it never ships to production.

// App.tsx
import { Clickly } from "useclickly";

export function App() {
  return (
    <>
      <YourApp />
      {process.env.NODE_ENV === "development" && <Clickly />}
    </>
  );
}

The toolbar renders a floating button in the bottom-right corner of the viewport. Click it to enter annotation mode.

Next.js App Router

Because Clickly is a Client Component, you need to wrap it in a provider that carries the "use client" directive. This pattern also lets you conditionally render based on NODE_ENV without leaking the import into server bundles.

// app/layout.tsx
import { ToolbarProvider } from "./ToolbarProvider";

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

// app/ToolbarProvider.tsx
"use client";
import { Clickly } from "useclickly";

export function ToolbarProvider() {
  if (process.env.NODE_ENV !== "development") return null;
  return <Clickly />;
}

Add useclickly and @useclickly/core to transpilePackages in next.config.js:

/** @type {import('next').NextConfig} */
module.exports = {
  reactStrictMode: true,
  transpilePackages: ["useclickly", "@useclickly/core"],
};

Vite

With Vite you can use dynamic imports to keep the package out of production bundles entirely.

// main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

let ClicklyComponent: React.ComponentType | null = null;
if (import.meta.env.DEV) {
  const mod = await import("useclickly");
  ClicklyComponent = mod.Clickly;
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
    {ClicklyComponent && <ClicklyComponent />}
  </React.StrictMode>
);

MCP server (optional)

Install the companion MCP server to let your AI agent read annotations directly without copy-paste. See the MCP guide for full setup instructions.

npx @useclickly/mcp-server install