Installation | Django

Create internal apps directly in your Django codebase with the Compose SDK. This guide will get you started with two starter apps in ~3 minutes.

1. Install the SDK

Use your package manager to install the Compose SDK.

pip install compose-sdk
# or
poetry add compose-sdk
# or
uv add compose-sdk

2. Create a new Django app

Creating a separate Django app for Compose will help organize your code better.

python manage.py startapp compose

3. Add starter apps

In the compose folder that you just created, create a new file called starter_apps.py, and add the following:

import compose_sdk as c

# For demo purposes. In a real app, you'd use your actual database.
db_users = [
    { "name": "John Doe", "email": "john@doe.com" },
    { "name": "Jane Smith", "email": "jane@smith.com" },
]

def view_users_handler(page: c.Page, ui: c.UI):
    page.add(lambda: ui.header("View Users", size="lg"))
    users = [*db_users] # fake database call
    page.add(lambda: ui.table("users-table", users))

def create_user_handler(page: c.Page, ui: c.UI):
    def on_submit(form):
        db_users.append({ "name": form["name"], "email": form["email"] })
        page.toast("User created successfully", appearance="success")
        page.link("view-users")

    page.add(lambda: ui.header("Create User", size="lg"))
    page.add(lambda: ui.form(
        "create-user-form",
        [
            ui.text_input("name"),
            ui.email_input("email")
        ],
        on_submit=on_submit
    ))


nav = c.Navigation(["view-users", "create-user"])

view_users_app = c.App(route="view-users", nav=nav, handler=view_users_handler)
create_user_app = c.App(route="create-user", nav=nav, handler=create_user_handler)

4. Start the Compose Client

In the apps.py file of the Compose app, add the following:

from django.apps import AppConfig
import os
import compose_sdk as c


class ComposeConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'compose'

    def ready(self):
        # Don't start in the auto-reload process
        if os.environ.get("RUN_MAIN") != "true":
            return

        # Do dynamic imports to avoid AppRegistryNotReady errors
        from .starter_apps import view_users_app, create_user_app

        client = c.Client(
            api_key="API_KEY_HERE",
            apps=[view_users_app, create_user_app]
        )

        client.connect_async()

connect_async vs connect

The Python SDK provides two methods to connect to the Compose web dashboard: connect_async and connect.

• connect_async starts the WebSocket connection in a separate background thread. Use this in environments like Django where blocking the main thread would interfere with request handling.
• connect runs the connection in the main thread. Use this when running a standalone Python process dedicated to Compose apps.

Replace API_KEY_HERE with your own Compose API key. Create a free account on Compose to get one.

5. Run your app

Start your Django server. Compose will automatically connect in the background.

python manage.py runserver

You should see your apps come online in the Compose web dashboard.

Next steps

1. Replace db_users with real database calls.
2. Go through Compose's core concepts to quickly become productive with the SDK.
3. Join the Discord community to ask questions and talk to the core team.