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.

PreviousAngular No-code Email Builder NextConnect the docs to your IDE

Last updated 3 months ago

Was this helpful?