# 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.