Django Beefree SDK Demo

A demo of Beefree SDK embedded within a Django application.

Introduction

This demo includes a Django app that embeds Beefree SDK's no‑code email builder using Django templates and a modern frontend build process with Vite and npm. This project demonstrates a Python‑first backend that securely obtains Beefree SDK tokens, while the browser loads and runs the SDK.

Docs: Beefree SDK Reference: This project's code in the beefree-django-app-demo GitHub repository.

While Django applications are Python‑based and commonly server‑rendered, you can still embed JavaScript libraries like Beefree SDK. The key is to split responsibilities:

• Django (server): securely requests a token from loginV2 using BEE_CLIENT_ID and BEE_CLIENT_SECRET and returns the full JSON to the browser.

• Browser (client): loads Beefree SDK via npm package, initializes it with the server‑provided token, and mounts the editor in a container div.

This project provides:

• A minimal Django app with an endpoint for token generation.

• A modern frontend build process using Vite and npm.

• A template with a container and a "Read the Docs" button.

• A frontend script that imports the SDK, starts it, and then loads a starter template for a smooth, interactive experience.

Quick start (clone and run)

# 1) Clone
git clone https://github.com/BeefreeSDK/beefree-django-app-demo.git
cd beefree-django-app-demo

# 2) Create venv and install Python deps
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3) Install Node.js dependencies and build frontend
npm install
npm install @beefree.io/sdk
npm run build

# 4) Configure environment (recommended: .env at project root)
# Create .env with your credentials
cat > .env << 'EOF'
DJANGO_SECRET_KEY=change-me
DJANGO_DEBUG=1
DJANGO_ALLOWED_HOSTS=*
BEE_CLIENT_ID=YOUR-CLIENT-ID
BEE_CLIENT_SECRET=YOUR-CLIENT-SECRET
EOF

# 5) Migrate and run (default host/port)
python manage.py migrate
python manage.py runserver

# Optional: run on a custom host/port
# (set DJANGO_ALLOWED_HOSTS accordingly, e.g., to your domain or IP)
# python manage.py runserver 9000
# python manage.py runserver 0.0.0.0:8080

Alternative: Using Makefile and build script

For convenience, the project includes a Makefile and build script:

# Using the build script (recommended for first-time setup)
./build.sh

# Or using Makefile commands
make setup  # Sets up Python venv, installs deps, runs migrations, builds frontend
make run    # Starts the Django development server

The build.sh script will:

• Check Node.js version (requires 18+)

• Install npm dependencies

• Install Beefree SDK package

• Build frontend assets

• Provide next steps

Open your server URL in the browser (for local dev, use the address shown by runserver).

You'll see a header with a "Read the Docs" button linking to the SDK docs. The Beefree SDK editor loads in the container and then loads the sample template. If you see any cached assets, do a hard refresh (Shift + Reload).

Development

For frontend development with hot reloading:

# Start the Django server in one terminal
python manage.py runserver

# Start the Vite dev server in another terminal
npm run dev

The Vite dev server will run on http://localhost:3000 and proxy API requests to Django on http://localhost:8000, providing hot reloading for frontend changes.

How it works

This section discusses how the Django applications works with Beefree SDK.

High‑level

The SDK is a JavaScript widget that runs client‑side in the user's browser. Django securely generates a Beefree SDK token server‑side via https://auth.getbee.io/loginV2 using BEE_CLIENT_ID and BEE_CLIENT_SECRET. The server returns the full JSON response to the browser. The browser initializes the SDK with that JSON: new BeefreeSDK({ ...token, v2: true }), then calls sdk.start(beeConfig, user, template, options) and/or sdk.load(template) as needed.

Django pieces

editor/views.py

• index renders templates/editor/index.html.

• bee_auth exposes POST /api/bee-auth: sends client_id, client_secret, and uid to Beefree loginV2 and returns the full JSON to the client.

beefree_demo/settings.py loads environment variables via django-environ (.env in project root recommended).

Frontend pieces

templates/editor/index.html: page structure, docs button, editor container div (id="beefree-editor-container"), status div (id="status"), and a <script type="module"> inclusion for the built JavaScript.

frontend/src/editor.js:

• Imports the Beefree SDK from npm package @beefree.io/sdk.

• Fetches the token from /api/bee-auth using async/await.

• Builds beeConfig with required container parameter, and optional language, onSave, and onError parameters.

• Includes status management functionality to show loading states and errors.

• Starts the editor with an empty template, then calls sdk.load(templateJson) to load the initial template.

frontend/src/styles.css: Modern CSS with CSS custom properties and responsive design.

Build process

package.json: Defines npm dependencies including @beefree.io/sdk. vite.config.js: Configures the build process to output to Django's static directory with proper asset organization. npm run build: Bundles the frontend code and assets for production.

Template initialization

The starter template is embedded directly in frontend/src/editor.js as the initialTemplate constant. Update the template object to change the default content.

Django architecture (explanation)

This section references concepts from this article to explain how Django architectures work at a high level. Reference this article for more information.

Note: The content in this section is not specific to this project, but all Django architectures in general. Skip if you are already familiar with these concepts.

At a high level, web apps separate concerns into three kinds of logic: input, business, and presentation. Django follows a pragmatic variant known as MTV (Model‑Template‑View):

• Model: defines and manages your data and business rules.

• Template: renders the user interface (HTML/CSS/JS) based on data passed from views.

• View: handles HTTP requests, orchestrates business logic, and returns responses.

URLs map incoming requests to views; views may talk to models and then render templates. This separation keeps code maintainable and testable while allowing each piece to evolve independently. For a deeper dive, see Django architecture overviews like this article.

Best practices for Beefree SDK in Django

• Generate tokens server‑side only; never expose BEE_CLIENT_SECRET in the browser.

• Return the entire loginV2 JSON to the client and construct the SDK with { ...token, v2: true }.

• Use sdk.start and include a valid container id in beeConfig.

• Load a design via sdk.load(template) after sdk.start(...).

• Use a modern build process (Vite/Webpack) for better development experience and optimized production builds.

How a JS SDK works in Django

Django renders HTML and serves static files, but the browser runs JavaScript. Beefree SDK is a client‑side library. Django's job is to:

• Render the page and serve static assets.

• Securely fetch and return the Beefree SDK token from loginV2.

• Provide endpoints and persistence for the app's data (if needed). The browser then loads the SDK and opens the editor with the server‑provided token.

File map

beefree_demo/
  settings.py       # loads .env, configures apps/static/templates
  urls.py           # routes root to the editor app
editor/
  views.py          # index page + /api/bee-auth (loginV2 proxy)
  urls.py           # app URL patterns
templates/editor/
  index.html        # container + docs button, includes built JS
frontend/
  src/
    editor.js       # import SDK, fetch token, start editor, load template
    styles.css      # modern CSS with responsive design
  index.html        # development template
package.json        # npm dependencies and scripts
vite.config.js      # build configuration
Makefile           # convenience commands (setup, run)
build.sh           # automated setup script
static/             # built assets (generated by npm run build)
  js/
  css/
  assets/

Troubleshooting

Editor stuck on loading spinner:

• Start with an empty template and call sdk.load(templateJson) after sdk.start(...). This project already does this in frontend/src/editor.js.

• Hard refresh (Shift + Reload) to avoid cached assets.

• Confirm POST /api/bee-auth is 200.

• Ensure you've run npm run build to generate the static assets.

Build errors:

• Make sure Node.js 18+ is installed.

• Run npm install to install dependencies.

• Ensure @beefree.io/sdk package is installed.

• Check for dependency conflicts.

Token errors (401/403):

• Verify BEE_CLIENT_ID and BEE_CLIENT_SECRET in .env, restart the server.