Integrating Topol Plugin into a Next.js Application

Next.js offers server-side rendering, static optimization, and a React-based framework—making it a modern, efficient foundation for embedding the Topol Plugin.

This guide provides a clear, step-by-step walkthrough for integrating the official React wrapper of the Topol Plugin into your existing Next.js project.

Before You Begin

Make sure you have:

• An existing Next.js application set up and running
• Access to your Topol API Token

Getting Your Topol API Token

1. Log in to your Topol account at https://app.topol.io.
2. Navigate to Settings -> Plugin.
3. Click New API Token, give it a name (e.g. my-topol-app), and whitelist your domains (localhost:3000, *.yourdomain.com).
4. Click on Show api key and copy the generated token. You'll need this later.

Step-by-Step Integration Guide

By following these steps, you'll have a clean, maintainable integration of Topol Plugin in your Next.js app—empowering your users with a powerful, in-app email template editor.

1. Install the React Integration Package

Install the official React wrapper for the Topol Plugin:

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

This package allows you to embed the editor as a native React component in your Next.js application.

For more details, refer to the npm package documentation.

2. Store Your API Key Securely

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

NEXT_PUBLIC_TOPOL_API_KEY=your_api_token_here

Store the API key in environment variables to ensure separation between development, staging, and production environments.

INFO

The userId should be set dynamically based on your current user's ID, as it's used for image storage separation and billing purposes.

3. Build a Client-Only TopolEditor Component

Create components/TopolEditor.tsx file with the following code:

"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:

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>
  );
}

Pass the current user's ID as a prop to ensure proper billing tracking. Replace getCurrentUserId() with your actual authentication logic to retrieve the current user's unique identifier.

5. Run and Test Locally

Start the development server:

npm run dev

Open http://localhost:3000 in your browser, which should load the Topol editor. Design a template, click Save, and verify your console logs both JSON and HTML. This confirms the editor is loaded and callbacks are wired correctly. Well done!

Next Steps

Once you successfully integrate the Plugin into your Next.js app, the exciting part begins. Our documentation offers many useful features that you can use to customize the editor’s appearance and functionality exactly as you want. Here are some of the features we suggest exploring:

• Handle additional events (onInit, onPreview, onUndoChange etc.) via the callbacks object. More details here.
• Integrate custom storage (AWS S3, Google Cloud, Cloudflare R2) or self-hosted storage. More details here.
• Replace the default File Manager with your custom asset manager. More details here.
• Integrate robust AI-powered features, such as AI Assistant, AI Chat or Custom AI Model.
• Explore all other Basic and Advanced Configuration options available in this documentation and apply them through the TOPOL_OPTIONS object. You can customize the editor color theme, language, labels, fonts and much, much more.

If you notice any features that could be helpful but are missing, please don't hesitate to reach out to our Support team. We're more than happy to pass your request to our developers, and they'll do their best to include it as quickly as possible.