Appearance

Lettr — the email API from the team behind Topol EditorThe email API that ships in an afternoonFrom the team behind Topol Editor

Integrating Topol Plugin into a Next.js application ​

This guide embeds the Topol Plugin in a Next.js app through the official React wrapper, @topol.io/editor-react.

The one Next.js-specific wrinkle is that the editor is a client-side component, so the wrapper has to load with SSR disabled. The steps below cover that and the rest of the setup.

Before you begin ​

This guide assumes two things are in place:

  • An existing Next.js application
  • A Topol API Token

Getting your Topol API Token ​

  1. Log in to your Topol account at https://app.topol.io.
  2. Go to Settings -> Plugin.
  3. Click New API Token, name it (for example, my-topol-app), and whitelist your domains (localhost:3000, *.yourdomain.com).
  4. Click Show API keys and copy the generated token, needed in step 2.

Integration steps ​

1. Install the React integration package ​

Install the official React wrapper for the Topol Plugin:

bash
npm install @topol.io/editor-react
# or
yarn add @topol.io/editor-react
# or
pnpm add @topol.io/editor-react

The wrapper embeds the editor as a native React component. Its npm page has more detail.

2. Store your API key securely ​

In your project root, create a .env.local file and add:

bash
NEXT_PUBLIC_TOPOL_API_KEY=your_api_token_here

Keeping the key in an environment variable separates it across development, staging, and production.

INFO

Set userId dynamically from the current user's ID. Topol uses it for image storage separation and billing.

3. Build a client-only TopolEditor component ​

Create components/TopolEditor.tsx:

tsx
"use client";
import dynamic from "next/dynamic";
import type { ITopolOptions } from "@topol.io/editor-react";

// Load the React wrapper only on the client
const TopolEditor = dynamic(
  () => import("@topol.io/editor-react").then((mod) => mod.default),
  { ssr: false }
);

interface TopolEditorWrapperProps {
  userId: string;
}

export default function TopolEditorWrapper({
  userId,
}: TopolEditorWrapperProps) {
  const options: ITopolOptions = {
    authorize: {
      apiKey: process.env.NEXT_PUBLIC_TOPOL_API_KEY!,
      userId: userId,
    },
    callbacks: {
      onSave(json, html) {
        console.log("Template saved:", { json, html });
      },
    },
  };

  return (
    <div style={{ width: "100%", height: "100vh" }}>
      <TopolEditor options={options} />
    </div>
  );
}

INFO

onSave is just one of many callback functions, which allow you to customize the essential editor events with your own logic. A full list of callbacks is available here.

4. Embed the editor in your Next.js page ​

Edit pages/index.tsx to include the wrapper:

tsx
import TopolEditorWrapper from "../components/TopolEditor";

export default function Home() {
  // Get the current user ID from your authentication system
  const currentUserId = getCurrentUserId(); // Replace with your actual user ID logic

  return (
    <main>
      <h1>Welcome to Your Email Editor</h1>
      <TopolEditorWrapper userId={currentUserId} />
    </main>
  );
}

Passing the user's ID as a prop keeps billing attributed to the right account. Replace getCurrentUserId() with your own authentication logic.

5. Run and test locally ​

Start the development server:

bash
npm run dev

Opening http://localhost:3000 loads the editor. Build a template, click Save, and check that the console logs both the JSON and the HTML, which confirms the editor and its callbacks are wired up.

Next steps ​

The editor has far more to configure through TOPOL_OPTIONS and the callbacks object. A few directions worth exploring:

For a feature that would help but is missing, contact our support team and we will pass the request to the developers.