---
title: "Integration into Next.js"
description: "Provide a step-by-step guide that will explain to developers the process of integrating the Topol Plugin into any Next.js application."
url: https://docs.topol.io/email-editor/guide/integration-nextjs.html
---

# 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](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](https://docs.topol.io/email-editor/guide/integration-nextjs.html#_2-store-your-api-key-securely).

## 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](https://www.npmjs.com/package/@topol.io/editor-react) 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](https://docs.topol.io/email-editor/guide/callbacks.html#callbacks).

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

-   Handle more events (`onInit`, `onPreview`, `onUndoChange`, and others) through the `callbacks` object. See the [callbacks reference](https://docs.topol.io/email-editor/guide/callbacks.html).
-   Integrate **custom** storage (AWS S3, Google Cloud, Cloudflare R2, DigitalOcean Spaces) or **self-hosted** storage. See [self-hosted storage](https://docs.topol.io/email-editor/guide/self-hosted-storage.html).
-   Replace the default **file manager** with your own asset manager. See [custom file manager](https://docs.topol.io/email-editor/guide/custom-filemanager.html#custom-file-manager).
-   Add **AI** features such as the [AI Assistant](https://docs.topol.io/email-editor/guide/ai-assistant.html), [AI Chat](https://docs.topol.io/email-editor/guide/chat-ai.html), or a [Custom AI Model](https://docs.topol.io/email-editor/guide/custom-ai.html).
-   Customize the editor's [color theme](https://docs.topol.io/email-editor/guide/themes.html), [language](https://docs.topol.io/email-editor/guide/i18n.html), [labels](https://docs.topol.io/email-editor/guide/custom-labels.html), and [fonts](https://docs.topol.io/email-editor/guide/custom-fonts.html).

For a feature that would help but is missing, [contact our support team](https://topol.io/contact) and we will pass the request to the developers.