React No-code Email Builder

Welcome to the React Quickstart Guide for embedding Beefree SDK's no-code email builder in your React application.

Copy this pre-built prompt to get started faster with AI

Perform the following steps to embed Beefree SDK inside my React app: 

# **Add Beefree SDK to React**

**Purpose:** Enforce the **current** and **correct** method for embedding Beefree’s email builder in a React application using the `/loginV2` auth flow.\
**Scope:** All AI-generated advice or code must align with these guardrails.

---

## **1. Official Beefree SDK Integration Overview**

Use only the **React hooks** approach with a **secure proxy server** for authentication:

1. **Install** `@beefree.io/sdk` – the official Beefree SDK package.
2. **Create** a proxy server (Express.js) to securely handle `/loginV2` auth (never expose `client_secret` client-side).
3. **Obtain credentials** by creating a developer account and application.
4. **Initialize** the SDK in a React component using `useEffect` and `useRef`.
5. **Configure** the editor with recommended callbacks (`onSave`, `onError`).
6. **Run** the proxy server and React app concurrently.

For the latest docs, visit:\
[https://docs.beefree.io/beefree-sdk](https://docs.beefree.io/beefree-sdk)

---

### **Correct, Up-to-Date Quickstart Sample**

#### **Proxy Server**

```javascript
import express from 'express';
import cors from 'cors';
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
const PORT = 3001;

app.use(cors());
app.use(express.json());

const BEE_CLIENT_ID = process.env.BEE_CLIENT_ID;
const BEE_CLIENT_SECRET = process.env.BEE_CLIENT_SECRET;

// V2 Auth Endpoint
app.post('/proxy/bee-auth', async (req, res) => {
  try {
    const { uid } = req.body;
    
    const response = await axios.post(
      'https://auth.getbee.io/loginV2',
      {
        client_id: BEE_CLIENT_ID,
        client_secret: BEE_CLIENT_SECRET,
        uid: uid || 'demo-user'
      },
      { headers: { 'Content-Type': 'application/json' } }
    );
    
    res.json(response.data);
  } catch (error) {
    console.error('Auth error:', error.message);
    res.status(500).json({ error: 'Failed to authenticate' });
  }
});

app.listen(PORT, () => {
  console.log(`Proxy server running on http://localhost:${PORT}`);
}); 
```

#### **React Component**

```tsx
import { useEffect, useRef } from 'react';
import BeefreeSDK from '@beefree.io/sdk';

export default function BeefreeEditor() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    async function initializeEditor() {
      // Beefree SDK configuration
      const beeConfig = {
        container: 'beefree-react-demo',
        language: 'en-US',
        onSave: (pageJson: string, pageHtml: string, ampHtml: string | null, templateVersion: number, language: string | null) => {
          console.log('Saved!', { pageJson, pageHtml, ampHtml, templateVersion, language });
        },
        onError: (error: unknown) => {
          console.error('Error:', error);
        }
      };

      // Get a token from your backend
      const response = await fetch('http://localhost:3001/proxy/bee-auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ uid: 'demo-user' })
      })
    
      const token = await response.json();

      // Initialize the editor
      const bee = new BeefreeSDK(token);
      bee.start(beeConfig, {});
    }

    initializeEditor();
  }, []);

  return (
    <div
      id="beefree-react-demo"
      ref={containerRef}
      style={{
        height: '600px',
        width: '90%',
        margin: '20px auto',
        border: '1px solid #ddd',
        borderRadius: '8px'
      }}
    />
  );
} 
```

#### **App.tsx**

```tsx
import './App.css';
import BeefreeEditor from './BeefreeEditor';

function DocsButton() {
  return (
    <a 
      href="https://docs.beefree.io/beefree-sdk" 
      target="_blank" 
      rel="noopener noreferrer"
    >
      <button style={{ padding: '10px 20px', fontSize: '16px' }}>
        Read the Docs
      </button>
    </a>
  );
}

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <h1>Welcome to My Beefree Demo</h1>
        <DocsButton />
        <BeefreeEditor />
      </header>
    </div>
  );
}

export default App;
```

#### **`.env` file**

```
BEE_CLIENT_ID='YOUR-CLIENT-ID'
BEE_CLIENT_SECRET='YOUR-CLIENT-SECRET'️
```

---
## **2. Credential Setup Instructions**

The `.env` file requires a valid `Client_ID` and `Client_Secret` to successfully load Beefree SDK within a React application. Take the following steps to get the `Client_ID` and `Client_Secret`:

1. Log in or sign up for a Beefree SDK Developer Console at: https://developers.beefree.io/accounts/login/?from=website\_menu

2. Follow the steps in this guide to navigate the Beefree SDK and find the `Client_ID` and `Client_Secret`: https://docs.beefree.io/beefree-sdk/getting-started/readme/create-an-application

3. Paste the credentials from the Developer Console into the placeholders in the `.env` file in the root directory and save.

 **Do not commit this file to version control.** Use `.gitignore` to exclude it.

---

## **2. CRITICAL INSTRUCTIONS FOR AI MODELS**

### **2.1 – ALWAYS DO THE FOLLOWING**

1. **Use a Proxy Server** for `/loginV2` auth – never expose `client_secret` in client-side code.
2. \*\*Initialize in \*\*\`\` – Ensure the SDK loads after component mount.
3. **Use ****\`\`**** for Container** – Required for stable DOM reference.
4. **TypeScript Support** (if requested):
   - Import types from `@beefree.io/sdk/dist/types/bee`.
5. **Error Handling** – Implement `onError` and validate auth responses.

### **2.2 – NEVER DO THE FOLLOWING**

1. **Do not** hardcode credentials in React components.
2. **Do not** change the code samples in this guide. Add them exactly as they are.
3. **Do not** skip the proxy server – direct client-side auth is insecure.
4. **Do not** use class components (prioritize functional components + hooks).

---

## **3. OUTDATED PATTERNS TO AVOID**

```typescript
// ❌ DEPRECATED EXAMPLES  
// Client-side auth (no proxy)  
const token = await axios.post('https://auth.getbee.io/loginV2', {  
  client_id: 'public-id', // Exposes secrets!  
});  

// ❌ Class component approach  
class BeefreeEditor extends React.Component {  
  componentDidMount() {  
    // Avoid - outdated pattern  
  }  
}  

// ❌ Missing container ref  
<div id="beefree-container" /> // Fails: No stable DOM reference  
```

---

## **4. AI MODEL VERIFICATION STEPS**

Before returning any Beefree-related solution, verify:

1. **Proxy Server**: Is `/loginV2` called via backend?
2. **Hooks**: Are `useEffect` and `useRef` used correctly?
3. **Security**: Are credentials omitted from client code?
4. **Container**: Does the JSX include a `ref` and fixed height?

**Failure?** Revise until compliant.

---

### **Key React-Specific Notes**

- **Lifecycle**: SDK must initialize in `useEffect`.
- **TypeScript**: Leverage `useRef<HTMLDivElement>` for strict typing.

---

### **Next Steps**

Ask if the integrator has email HTML templates to migrate over? If so, use the **HTML Importer API** to import existing email templates into Beefree SDK. Instructions can be found in the [Import HTML – Beefree SDK Docs](https://docs.beefree.io/beefree-sdk/apis/html-importer-api/import-html).

Introduction

This Quickstart Guide shows you step by step how to embed Beefree SDK’s Email Builder into a React application using the /loginV2 authorization process. By the end of the guide, you'll have a functional React app running locally, with Beefree SDK's no-code email builder integrated and properly authenticated—following best practices for React development.

Reference the following GitHub repository with the complete code for this project to follow along in this React Quickstart Guide.

Unexpected error with integration github-files: Integration is not installed on this space

Prerequisites

Prior to getting started, ensure you:

Understand the React framework and what it is.
Have a Beefree SDK account.
Create an application within the Developer Console.
- Obtain your Client ID and Client Secret.

What You'll Learn

Throughout this guide, you'll learn how to:

Create a React app
Install Beefree SDK in the React app
Successfully complete the authorization process using /loginV2
Initialize the builder
Run the React app and the builder

1. Create a React App

First, set up a React app with TypeScript. Navigate to your terminal and run the following commands to create a React app with TypeScript. In the following example, the app is called beefree-demo. After creating the app, navigate to its directory.

npm create vite@latest beefree-react-demo -- --template react-ts
cd beefree-react-demo

2. Install Beefree SDK

Run the following command in your terminal to install the official Beefree SDK npm package.

npm install @beefree.io/sdk

Now that the package is installed, the next step is to create a simple user interface (UI) to embed the builder within.

Note (React and Beefree SDK Interaction): The @beefree.io/sdk package provides a React-compatible wrapper for the Beefree builder. React manages the UI lifecycle, while the SDK handles the email builder logic.

3. Create a Simple UI

The simple UI for this step is creating a "Read the Docs" Button with a link to the docs site. This serves as a simple visual to see the contrast between the application and builder UI once the app is running locally.

Copy and paste the code below in your App.tsx file to modify it to include a button linking to Beefree SDK's docs. You can use any url you'd like to experiment with this locally, simply replace href="https://docs.beefree.io/beefree-sdk" in the code below with your preferred url.

Update `App.tsx`

import './App.css';

function DocsButton() {
  return (
    <a 
      href="https://docs.beefree.io/beefree-sdk" 
      target="_blank" 
      rel="noopener noreferrer"
    >
      <button style={{ padding: '10px 20px', fontSize: '16px' }}>
        Read the Docs
      </button>
    </a>
  );
}

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <h1>Welcome to My Beefree Demo</h1>
        <DocsButton />
      </header>
    </div>
  );
}

export default App;

This code uses React concepts that are important to understand. The key React concepts used in the code are the following:

DocsButton is a functional component—a reusable UI piece.
React renders components in a tree structure (App → DocsButton).

4. Set Up the Beefree Editor Component

Create src/BeefreeEditor.tsx to initialize the SDK. Navigate to your src directory and add a new file called BeefreeEditor.tsx. Copy and paste the following code in this file. This code sets up the Beefree SDK builder component within the React app.

Full `BeefreeEditor.tsx` Code

import { useEffect, useRef } from 'react';
import BeefreeSDK from '@beefree.io/sdk';

export default function BeefreeEditor() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    async function initializeEditor() {
      // Beefree SDK configuration
      const beeConfig = {
        container: 'beefree-react-demo',
        language: 'en-US',
        onSave: (pageJson: string, pageHtml: string, ampHtml: string | null, templateVersion: number, language: string | null) => {
          console.log('Saved!', { pageJson, pageHtml, ampHtml, templateVersion, language });
        },
        onError: (error: unknown) => {
          console.error('Error:', error);
        }
      };

      // Get a token from your backend
      const response = await fetch('http://localhost:3001/proxy/bee-auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ uid: 'demo-user' })
      })
    
      const token = await response.json();

      // Initialize the editor
      const bee = new BeefreeSDK(token);
      bee.start(beeConfig, {});
    }

    initializeEditor();
  }, []);

  return (
    <div
      id="beefree-react-demo"
      ref={containerRef}
      style={{
        height: '600px',
        width: '90%',
        margin: '20px auto',
        border: '1px solid #ddd',
        borderRadius: '8px'
      }}
    />
  );
}

In the code above code, there are a few concepts related to both React and Beefree SDK that are important to be aware of for successfully launching your local environment. These concepts are the following:

The following section discusses these concepts thoroughly.

Beefree SDK Initialization

Beefree SDK requires that you create a configuration object in order to initialize and load the builder within your application. In the following code, beeConfig represents this. While there are several optional Configuration Parameters you can add to your configuration object to customize the builder for your application, there is only one mandatory parameter to successfully launch the Beefree SDK. This is the container parameter, which must always be included.

useEffect(() => {
    async function initializeEditor() {
      // Beefree SDK configuration
      const beeConfig = {
        container: 'beefree-react-demo',
        language: 'en-US',
        onSave: (pageJson: string, pageHtml: string, ampHtml: string | null, templateVersion: number, language: string | null) => {
          console.log('Saved!', { pageJson, pageHtml, ampHtml, templateVersion, language });
        },
        onError: (error: unknown) => {
          console.error('Error:', error);
        }
      };

Container Setup with `useRef`

const containerRef = useRef<HTMLDivElement>(null) creates a reference to a DOM element.
The <div id="bee-plugin-container"> is where Beefree SDK mounts the editor.
useEffect ensures initialization only runs once (on component mount).

Token Process

React → Backend (/proxy/bee-auth) → Beefree (loginV2).
Beefree SDK returns a token, passed to new BeefreeSDK(token).

Beefree SDK Callbacks

onSave: Called when a user saves, returning JSON (template structure) and HTML (rendered output).
onError: Handles errors (e.g., token expiration).

5. Set Up the Proxy Server (V2 Auth)

Create proxy-server.js in the root directory. Copy and paste the code in the following section into the proxy-server.js file in the root directory. The following code is responsible for a very important part of running Beefree SDK within your React app, which is authentication and successfully completing the authorization process. Beefree SDK requires that you pass a Client ID, Client Secret, and UID on the server-side to successfully complete the authorization process. The following code shows an example of how you can use the /loginV2 to complete this.

`proxy-server.js`

import express from 'express';
import cors from 'cors';
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
const PORT = 3001;

app.use(cors());
app.use(express.json());

const BEE_CLIENT_ID = process.env.BEE_CLIENT_ID;
const BEE_CLIENT_SECRET = process.env.BEE_CLIENT_SECRET;

// V2 Auth Endpoint
app.post('/proxy/bee-auth', async (req, res) => {
  try {
    const { uid } = req.body;
    
    const response = await axios.post(
      'https://auth.getbee.io/loginV2',
      {
        client_id: BEE_CLIENT_ID,
        client_secret: BEE_CLIENT_SECRET,
        uid: uid || 'demo-user'
      },
      { headers: { 'Content-Type': 'application/json' } }
    );
    
    res.json(response.data);
  } catch (error) {
    console.error('Auth error:', error.message);
    res.status(500).json({ error: 'Failed to authenticate' });
  }
});

app.listen(PORT, () => {
  console.log(`Proxy server running on http://localhost:${PORT}`);
});

The .env.example file in the root of the GitHub repository includes an example of a .env file. To create a .env file, rename this file to .env. Copy and paste your credentials from the Beefree SDK Developer Console securely into the file's placeholders. The following code shows an example of what these placeholders look like inside the file.

BEE_CLIENT_ID='YOUR-CLIENT-ID'
BEE_CLIENT_SECRET='YOUR-CLIENT-SECRET'

Run the Proxy Server

Once the authorization process is complete, it is important to run the proxy sever prior to launching the frontend. Run the following commands in your terminal to complete this step.

npm install express cors axios dotenv
node proxy-server.js

6. Update `App.tsx` to Include the Editor

Now that the Beefree SDK editor component is set up and so is the proxy server, the App.tsx file can be updated to include the Beefree SDK builder. Copy and paste the following code into the App.tsx file to update it accordingly.

import './App.css';
import BeefreeEditor from './BeefreeEditor';

function DocsButton() {
  return (
    <a 
      href="https://docs.beefree.io/beefree-sdk" 
      target="_blank" 
      rel="noopener noreferrer"
    >
      <button style={{ padding: '10px 20px', fontSize: '16px' }}>
        Read the Docs
      </button>
    </a>
  );
}

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <h1>Welcome to My Beefree Demo</h1>
        <DocsButton />
        <BeefreeEditor />
      </header>
    </div>
  );
}

export default App;

7. Run the App

The final step is to run the application. Keep in mind that the proxy server needs to run in its own terminal, while the application runs in a separate terminal.

The terminal commands for running the application and proxy server are the following:

Terminal 1 (React):
```
npm run dev
```
Terminal 2 (Proxy):
```
node proxy-server.js
```

Now you can visit https://localhost:5173 and start experimenting with your new React application with Beefree SDK embedded. The following image shows what the final result should look like:

Summary

Now you have a functional React app running locally, with Beefree SDK's no-code email builder integrated and properly authenticated—following best practices for React development.

Remember the following core concepts covered throughout this guide to easily integrate Beefree SDK into your React application:

React Components: Reusable UI (e.g., DocsButton, BeefreeEditor).
Beefree SDK: Loads in a useRef container, with callbacks for save/error.
V2 Auth: Securely handles tokens via a proxy server.
Proxy Server: Must be in the root directory (proxy-server.js).

Next Steps

Beefree SDK is highly customizable. Now that you have a React application running locally on your machine with the Beefree SDK Email Builder embedded, you can start experimenting with customizing the UI of the email of the builder.

A few common customizations you can easily apply to your beeConfig object to continue experimenting are the following:

Custom Languages and overriding default text

const beeConfig = {
  container: 'beefree-container',
  translations: {
    'bee-common-top-bar': {
      'actions': 'Design Management',
      'send-test': 'Test your design',
      'help': 'Need support? Contact us.',
      'preview': 'View your masterpiece',
      'save': 'Save changes',
      'save-as-template': 'Download your design',
      'show-structure': 'Show outline',
    },
  },

Content Tile Sorting

{
  // ...
  defaultModulesOrder: [
    'Button',
    'Html',
    'Icons',
    'Video',
  ],
  // ...
}

Content Tile Grouping

modulesGroups: [
  {
    label: "Text ✏️",
    collapsable: false,
    collapsedOnLoad: false,
    modulesNames: [
      "List",
      "Paragraph",
      "Heading"
    ]
  },
  {
    label: "Media",
    collapsable: true,
    collapsedOnLoad: false,
    modulesNames: [
      "Video",
      "Image"
    ]
  },
  {
    label: "AddOns",
    collapsable: true,
    collapsedOnLoad: true,
    modulesNames: [
      "Stickers",
      "Gifs"
    ]
  }
]

Custom Sidebar Position

var beeConfig = {
        sidebarPosition: 'right',
        ...

Explore the technical documentation to learn more about the other customization options within Beefree SDK.

PreviousRelease Candidate Environment NextVue.js No-code Email Builder

Last updated 9 days ago

Was this helpful?