# Django Beefree SDK Demo

## 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](https://docs.beefree.io/beefree-sdk)\
**Reference:** This project's code in the [beefree-django-app-demo GitHub repository](https://github.com/BeefreeSDK/beefree-django-app-demo).

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)

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

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

```bash
# 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](https://www.interviewbit.com/blog/django-architecture/) to explain how Django architectures work at a high level. Reference [this article](https://www.interviewbit.com/blog/django-architecture/) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.beefree.io/beefree-sdk/quickstart-guides/django-beefree-sdk-demo.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.