Other .mdc

BeefreeSDK Nocode Content Editor

Cursor rules for embedding Beefree SDK's no-code content editors (for emails, pages, and popups) into a web application.

Nasıl kullanılır
  1. Kural içeriğini kopyala.
  2. Projenin root klasöründe şu dosyayı oluştur: .cursorrules veya .cursor/rules/beefreeSDK-nocode-content-editor.mdc
  3. İçeriği yapıştır ve kaydet.

Bu kural hakkında

Beefree SDK Guidelines

Guidelines and best practices for building applications with Beefree SDK, including installation, authentication, configuration, customization, and template management.

Installation Guidelines

Package Installation

  • Install the Beefree SDK package using npm or yarn: 
    npm install @beefree.io/sdk
# or
yarn add @beefree.io/sdk

Dependencies

  • Beefree SDK requires the following core dependencies: 
    {
  "dependencies": {
    "@beefree.io/sdk": "^9.0.2-fix-optional-url-config.0",
    "axios": "^1.10.0",
    "express": "^5.1.0",
    "cors": "^2.8.5",
    "dotenv": "^17.2.0"
  }
}

Environment Setup

  • Create a .env file in your project root with your Beefree credentials: 
    BEE_CLIENT_ID=your_client_id_here
BEE_CLIENT_SECRET=your_client_secret_here

Authentication Guidelines

Proxy Server Setup

  • ALWAYS use a proxy server for authentication to protect your credentials
  • Create a proxy server file (e.g., proxy-server.js) to handle authentication: 
    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}`);
});

Authentication Process

  • Use the V2 authentication endpoint: https://auth.getbee.io/loginV2
  • Pass the ENTIRE API response to the Beefree SDK, not just the token
  • Example authentication call: 
    const token = await fetch('http://localhost:3001/proxy/bee-auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ uid: 'demo-user' })
}).then(res => res.json());

Container Setup Guidelines

HTML Container

  • Create a dedicated container element for the Beefree SDK: 
    <div id="beefree-sdk-container"></div>

CSS Styling

  • Style the container to ensure proper display: 
    #beefree-sdk-container {
  position: absolute;
  top: 0px;
  bottom: 0px;
  left: 0px;
  right: 0px;
  height: 600px;
  width: 90%;
  margin: 20px auto;
  border: 1px solid #ddd;
  border-radius: 8px;
}

React Container

  • For React applications, the following code snippet shows an example using refs to manage the container: 
    const containerRef = useRef<HTMLDivElement>(null);

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

Configuration Guidelines

Required Configuration Parameters

  • ALWAYS include the container parameter in your configuration: 
    const beeConfig = {
  container: 'beefree-sdk-container', // Required
  language: 'en-US'
};

Optional Configuration Parameters

  • Customize your SDK with optional parameters: 
    const beeConfig = {
  container: 'beefree-sdk-container', // Required
  language: 'en-US',
  specialLinks: [
    {
      type: "unsubscribe",
      label: "Unsubscribe",
      link: "http://[unsubscribe]/",
    },
    {
      type: "subscribe",
      label: "Subscribe",
      link: "http://[subscribe]/",
    },
  ],
  mergeTags: [
    {
      name: "First Name",
      value: "[first_name]",
    },
    {
      name: "Last Name",
      value: "[last_name]",
    },
    {
      name: "Email",
      value: "[email]",
    },
  ]
};

Callback Functions

  • Implement essential callback functions for proper functionality: 
    const beeConfig = {
  container: 'beefree-sdk-container',
  onSave: function (jsonFile, htmlFile) {
    console.log("Template saved:", jsonFile);
    // Implement custom save logic here
  },
  onAutoSave: function (jsonFile) {
    console.log("Auto-saving template...");
    localStorage.setItem("email.autosave", jsonFile);
  },
  onSend: function (htmlFile) {
    console.log("Email ready to send:", htmlFile);
    // Implement custom send logic here
  },
  onError: function (errorMessage) {
    console.error("Beefree SDK error:", errorMessage);
    // Handle errors appropriately
  }
};

SDK Initialization Guidelines

Basic Initialization

  • Initialize the Beefree SDK with proper error handling: 
    async function initializeBeefree(authResponse) {
  try {
    const bee = new BeefreeSDK(authResponse);
    bee.start(beeConfig, {});
    console.log('Beefree SDK initialized successfully');
  } catch (error) {
    console.error('Failed to initialize Beefree SDK:', error);
  }
}

React Integration

  • For React applications, the following code snippet shows an example using useEffect for initialization: 
    useEffect(() => {
  async function initializeEditor() {
    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);
      }
    };

    const token = await fetch('http://localhost:3001/proxy/bee-auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ uid: 'demo-user' })
    }).then(res => res.json());

    const bee = new BeefreeSDK(token);
    bee.start(beeConfig, {});
  }

  initializeEditor();
}, []);

Template Loading Guidelines

Loading Templates

  • Use the start() method with template data to load existing templates: 
    // Load template from localStorage
const selectedTemplate = JSON.parse(localStorage.getItem('currentEmailData'));

if (selectedTemplate) {
  beefreeSDKInstance.start(selectedTemplate);
  console.log('Loaded template from localStorage');
} else {
  // Start with empty template
            beefreeSDKInstance.start();
        console.log('Started with empty template');
}

Template Storage

  • Store templates in localStorage for persistence while testing: 
    // Save template data
localStorage.setItem('currentEmailData', JSON.stringify(templateData));
localStorage.setItem('currentEmailName', emailName);

// Load template data
const emailData = localStorage.getItem('currentEmailData');
const emailName = localStorage.getItem('currentEmailName');

Autosave Functionality

  • Implement autosave to prevent data loss: 
    onAutoSave: function (jsonFile) {
  console.log("Auto-saving template...");
  localStorage.setItem("email.autosave", jsonFile);
}

HTML Import Guidelines

HTML Importer API

  • Use the HTML Importer API to convert existing HTML templates to Beefree SDK format
  • API endpoint: https://api.getbee.io/v1/conversion/html-to-json
  • Reference: HTML Importer API Documentation

Import Process

  • Convert HTML templates to Beefree SDK’s native JSON format: 
    const response = await fetch('https://api.getbee.io/v1/conversion/html-to-json', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer Enter Dev Console API Key as Bearer token",
    "Content-Type": "text/html"
  },
  body: "<!DOCTYPE html><html><body><h1>Hello World</h1></body></html>"
}); 
const data = await response.json();

Loading Imported Templates

  • Load imported templates into the Beefree SDK: 
    const importedTemplate = await importHtmlTemplate(htmlContent);
beefreeSDK.start(importedTemplate);

Error Handling Guidelines

onError Callback

  • ALWAYS implement the onError callback to handle SDK errors: 
    onError: function (errorMessage) {
  console.error("Beefree SDK error:", errorMessage);
  // Display user-friendly error message
  document.getElementById('beefree-sdk-container').innerHTML = 
    '<div class="error">Error loading Beefree SDK: ' + errorMessage.message + '</div>';
}

Authentication Error Handling

  • Handle authentication failures gracefully: 
    function getBeeToken(callback) {
  fetch('/api/beefree/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ uid: beeConfig.uid })
  })
  .then(response => {
    if (!response.ok) throw new Error('Auth failed: ' + response.status);
    return response.json();
  })
  .then(data => {
    callback(data);
  })
  .catch(error => {
    console.error('Error getting Beefree token:', error);
    document.getElementById('beefree-sdk-container').innerHTML = 
      '<div class="error">Failed to authenticate with Beefree. Please check your credentials and try again.</div>';
  });
}

Template Change Tracking Guidelines

Track Message Changes

Change Detection

  • Use the onChange callback to track template changes: 
    onChange: function (jsonFile, response) {
console.log('json', jsonFile);
console.log('response', response);
  },

Customization Guidelines

UI Customization

Customize the Beefree SDK appearance with:

Language Customization

  • Set the language for internationalization: 
    const beeConfig = {
  container: 'beefree-sdk-container',
  language: 'en-US', // or 'es-ES', 'fr-FR', etc.
};
  • Configure merge tags and special links for email personalization: 
    const beeConfig = {
  container: 'beefree-sdk-container',
  mergeTags: [
    { name: "First Name", value: "[first_name]" },
    { name: "Last Name", value: "[last_name]" },
    { name: "Email", value: "[email]" },
    { name: "Company", value: "[company]" }
  ],
  specialLinks: [
    { type: "unsubscribe", label: "Unsubscribe", link: "http://[unsubscribe]/" },
    { type: "subscribe", label: "Subscribe", link: "http://[subscribe]/" },
    { type: "webview", label: "View in Browser", link: "http://[webview]/" }
  ]
};

Other Customizations

Reference the official Beefree SDK technical documentation for a comprehnsive reference of possible customizations.

Best Practices

Performance Optimization

  • Initialize the Beefree SDK only when it is actually needed in your application.
  • Properly clean up SDK resources when they are no longer required (e.g., when navigating away or closing the editor).
  • Handle errors gracefully to prevent application crashes or unexpected behavior.

Security

  • Never expose your Beefree SDK client credentials in any frontend or public code.
  • Always use a secure backend or proxy server to handle authentication and sensitive operations.
  • Validate and sanitize all user inputs before passing them to the SDK to prevent security vulnerabilities.

User Experience

  • Show appropriate loading indicators while the SDK is initializing or performing operations.
  • Display clear and helpful error messages to users if something goes wrong.
  • Implement automatic saving or progress tracking to prevent data loss.

Code Organization

  • Keep SDK configuration separate from initialization and business logic for better maintainability.
  • Use strong typing (e.g., TypeScript or similar) where possible to improve code safety and clarity.
  • Ensure robust error handling throughout your integration, regardless of the tech stack or framework used.

Examples

Complete React Component

Reference the full project at beefree-react-demo.

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

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

  useEffect(() => {
    async function initializeEditor() {
      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);
        }
      };

      const token = await fetch('http://localhost:3001/proxy/bee-auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ uid: 'demo-user' })
      }).then(res => res.json());

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

Complete HTML Implementation

Reference the complete project at Beefree SDK multiple-versions-concept.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Beefree SDK - Email Builder</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style type="text/css">
      #beefree-sdk-container {
        position: absolute;
        top: 0px;
        bottom: 0px;
        left: 0px;
        right: 0px;
      }
    </style>
  </head>
  <body>
    <div id="beefree-sdk-container"></div>
    <!-- Bundle the official @beefree.io/sdk package and expose BeefreeSDK from your app entrypoint. -->
    <script type="text/javascript">
      const beeConfig = {
            container: 'beefree-sdk-container',
    uid: 'demo-user-' + Date.now(),
    language: 'en-US',
        onSave: function (jsonFile, htmlFile) {
          console.log("Template saved:", jsonFile);
        },
        onError: function (errorMessage) {
          console.error("Beefree SDK error:", errorMessage);
        }
      };

      function getBeeToken(callback) {
        fetch('/api/beefree/auth', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ uid: beeConfig.uid })
        })
        .then(response => response.json())
        .then(data => callback(data))
        .catch(error => {
          console.error('Error getting Beefree token:', error);
        });
      }

      function initializeBeefree(authResponse) {
        const bee = new BeefreeSDK(authResponse);
        bee.start(beeConfig, {});
      }

      getBeeToken(initializeBeefree);
    </script>
  </body>
</html>

Benzer kurallar

Alpha Skills Quant Factor Research Other

Quantitative factor research skills for Cursor. Evaluate factors, run backtests, mine new alpha through natural language.

PatrickJS/awesome-cursorrules
Anti Overengineering Other

Prevent AI over-engineering by keeping changes scoped, simple, and directly tied to the user's request

PatrickJS/awesome-cursorrules
Anti Sycophancy Code Discipline Other

Anti-sycophancy directives for code review and generation. Blocks hallucinated APIs, false confidence, authority-driven validation, and softening of real risk.

PatrickJS/awesome-cursorrules
Aspnet Abp Other

Cursor rules for Aspnet Abp.

PatrickJS/awesome-cursorrules
BeefreeSDK Other

Guidelines and best practices for building applications with [Beefree SDK](https://docs.beefree.io/beefree-sdk), including installation, authentication, configuration, customization, and template management

PatrickJS/awesome-cursorrules
Clean Code Other

Guidelines for writing clean, maintainable, and human-readable code. Apply these rules when writing or reviewing code to ensure consistency and quality.

PatrickJS/awesome-cursorrules
Daha fazla: Other →