Quickstart

Compose is an open-source platform that makes it dramatically faster for developers to build and share internal tools with their team - without leaving their codebase.

What is Compose?

The platform has two parts:

• Build internal tools with just backend code using our SDKs for Python and TypeScript.
• Use and share those tools via your team's Compose web dashboard.

Here's a simple tool that displays a table of users from your database:

TypeScript / JavaScript

In your codebase:

import { Compose } from "@composehq/sdk";
import { database } from "../database";

const viewUsersApp = new Compose.App({
    route: "view-users",
    handler: async ({ page, ui }) => {
        const users = await database.selectUsers() // query your database
        page.add(() => ui.table("users-table", users)); // display results in a table
    }
})

Python

In your codebase:

import compose_sdk as c
from database import database

def view_users_handler(page: c.Page, ui: c.UI):
    users = database.select_users() # query your database
    page.add(lambda: ui.table("users-table", users)) # display results in a table

view_users_app = c.App(route="view-users", handler=view_users_handler)

In your team's Compose web dashboard:

The Compose SDK includes tables, forms, charts, file uploads, and 40+ other components to build whatever you need in just a few lines of code. Since the SDK is installed into your backend, connecting these components to your own data and logic is as easy as importing functions and calling them within the Compose Apps that you define.

The Compose web dashboard renders beautiful, responsive UIs for your tools and enables you to share them with your entire team. It also includes audit logs, RBAC, and other useful features to manage your tools without any configuration on your end.

Under the hood, the web dashboard maintains a secure, proxied websocket connection to the Compose SDK to run the tools you build.

Compose's biggest benefit is speed and simplicity, but it's also fully featured and scales to support complex, reactive, multi-page tools when you need it.

Installation

The best way to use Compose is by installing it as a dependency in your server-side application. This enables you to easily share code between your Compose Apps and the rest of your codebase, and also run your Compose Apps in production without deploying a separate service.

If you're just exploring for now or prefer to start from scratch, you can also initialize a new project with the SDK installed.

TypeScript / JavaScript

Python

Add to existing project

1. Install the SDK

TypeScript / JavaScript

npm install @composehq/sdk

Note on serverless frameworks

Compose is a pure Node.js library that integrates with most major frameworks and runtimes, but it does require running on a long-running server instead of a serverless environment since the SDK maintains a streaming connection to the web dashboard.

If you use a serverless framework like Next.js, you can easily deploy the SDK as a separate service.

Python

pip install compose-sdk

2. Define some starter apps

TypeScript / JavaScript

Let's create an internal tool that displays a table of users and allows you to create new users. You can copy this code directly into a new file (e.g. ./src/compose.ts):

import { Compose } from "@composehq/sdk";

const nav = new Compose.Navigation(
    ["view-users", "create-user"],
    { logoUrl: "https://composehq.com/dark-logo-with-text.svg"} // replace with your own logo!
)

// fake list of users
const dbUsers = [
    { name: "John Doe", email: "john@doe.com" },
    { name: "Jane Smith", email: "jane@smith.com" },
]

const viewUsersApp = new Compose.App({
    route: "view-users",
    navigation: nav,
    handler: async ({ page, ui }) => {
        page.add(() => ui.header("View Users", { size: "lg" }))
        const users = [...dbUsers] // fake database call
        page.add(() => ui.table("users-table", users));
    }
})

const createUserApp = new Compose.App({
    route: "create-user",
    navigation: nav,
    handler: async ({ page, ui }) => {
        page.add(() => ui.header("Create User", { size: "lg" }))
        page.add(() => ui.form(
            "create-user-form",
            [
                ui.textInput("name"),
                ui.emailInput("email")
            ],
            {
                onSubmit: async (form) => {
                    dbUsers.push({ name: form.name, email: form.email });
                    page.toast("User created successfully", { appearance: "success" });
                    page.link("view-users");
                }
            }
        ))
    }
})

const composeClient = new Compose.Client({
    apiKey: "API_KEY_HERE", // replace with your own API key
    apps: [viewUsersApp, createUserApp]
});

export { composeClient };

Python

Let's create an internal tool that displays a table of users and allows you to create new users. You can copy this code directly into a new file (e.g. ./src/compose.py):

import compose_sdk as c

nav = c.Navigation(
    ["view-users", "create-user"],
    logo_url="https://composehq.com/dark-logo-with-text.svg" # replace with your own logo!
)

# fake list of users
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
    ))

compose_client = c.Client(
    api_key="API_KEY_HERE", # replace with your own API key
    apps=[
        c.App(route="view-users", navigation=nav, handler=view_users_handler),
        c.App(route="create-user", navigation=nav, handler=create_user_handler)
    ]
)

Create an account on Compose to get an API key (it's free)!

3. Start the Compose Client

TypeScript / JavaScript

import express from "express";
import { composeClient } from "./compose";

// An example express server.
const app = express();

app.listen(3000, () => {
    console.log("Server is running on port 3000");
    composeClient.connect();
});

The above shows an express server, but the process is identical for any server-side framework.

Python

# Example Flask server
from flask import Flask
from compose import compose_client

compose_client.connect_async()
app = Flask(__name__)

@app.route("/")
def hello_world():
    return "<p>Hello, World!</p>"

The above shows a Flask server, but the process is identical for any server-side framework.

note

connect_async() is a non-blocking call that enables Compose to run without blocking the main server thread. If necessary, Compose also supports a blocking connect() function that runs Compose on the main thread.

4. Run the server

Run your server's normal dev command, e.g:

TypeScript / JavaScript

npm run dev

Python

python main.py

Go to the Compose dashboard and your app should appear! Afterwards, keep going with next steps.

Initialize as new project

Compose can be run as a dedicated service, which is useful if you're starting a new project or want to maintain separate environments for your server and internal tools.

Automatic Installation

Setup a new project with Compose using a single npx command in your terminal.

node

# TypeScript
npx @composehq/create@latest

# JavaScript
npx @composehq/create@latest --lang=javascript

python

npx @composehq/create@latest --lang=python

If you don't have npx on your machine, you can use the manual installation instructions below.

Manual Installation

node

Create a project directory

mkdir compose && cd compose

Initialize the project, and set the project type to module to enable modern JavaScript import/export syntax.

npm init -y && npm pkg set type=module

Install the Compose SDK

npm install @composehq/sdk

If you're using TypeScript, install the TypeScript compiler and tsx, which we'll use to run our app during development.

npm install --save-dev typescript tsx

Create a new file called app.ts (or app.js) and paste the following starter code:

import { Compose } from "@composehq/sdk";

const nav = new Compose.Navigation(
    ["view-users", "create-user"],
    { logoUrl: "https://composehq.com/dark-logo-with-text.svg"} // replace with your own logo!
)

// fake list of users
const dbUsers = [
    { name: "John Doe", email: "john@doe.com" },
    { name: "Jane Smith", email: "jane@smith.com" },
]

const viewUsersApp = new Compose.App({
    route: "view-users",
    navigation: nav,
    handler: async ({ page, ui }) => {
        page.add(() => ui.header("View Users", { size: "lg" }))
        const users = [...dbUsers] // fake database call
        page.add(() => ui.table("users-table", users));
    }
})

const createUserApp = new Compose.App({
    route: "create-user",
    navigation: nav,
    handler: async ({ page, ui }) => {
        page.add(() => ui.header("Create User", { size: "lg" }))
        page.add(() => ui.form(
            "create-user-form",
            [
                ui.textInput("name"),
                ui.emailInput("email")
            ],
            {
                onSubmit: async (form) => {
                    dbUsers.push({ name: form.name, email: form.email });
                    page.toast("User created successfully", { appearance: "success" });
                    page.link("view-users");
                }
            }
        ))
    }
})

const client = new Compose.Client({
    apiKey: "API_KEY_HERE", // replace with your own API key
    apps: [viewUsersApp, createUserApp]
});

client.connect();

Create an account on Compose to get an API key (it's free)!

Finally, run your project's dev command, e.g:

# TypeScript
npx tsx --watch src/index.ts

# JavaScript
node --watch src/index.js

python

First, create a new project directory and virtual environment.

mkdir compose && cd compose
python -m venv .venv

Activate the virtual environment.

# macOS/Linux
source .venv/bin/activate

# Windows command prompt
.venv\Scripts\Activate.bat

# Windows PowerShell
.venv\Scripts\Activate.ps1

Install the Compose SDK.

pip install compose-sdk

Optionally, install py-mon, a lightweight file watcher that will automatically restart your app when you make code changes.

pip install py-mon

Create a new file called app.py and paste the following starter code:

import compose_sdk as c

nav = c.Navigation(
    ["view-users", "create-user"],
    logo_url="https://composehq.com/dark-logo-with-text.svg" # replace with your own logo!
)

# fake list of users
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
    ))

client = c.Client(
    api_key="API_KEY_HERE", # replace with your own API key
    apps=[
        c.App(route="view-users", navigation=nav, handler=view_users_handler),
        c.App(route="create-user", navigation=nav, handler=create_user_handler)
    ]
)

client.connect()

Create an account on Compose to get an API key (it's free)!

Finally, run your project's dev command, e.g:

# Using py-mon
pymon app.py

# Using python
python app.py

Go to the Compose dashboard and your app should appear!

Next Steps

TypeScript / JavaScript

• Try replacing dbUsers with real data from your own database!
• Skim through Compose's core concepts to quickly become productive with the SDK.
• Join the Discord community to ask questions and talk to the core team.

Python

• Try replacing db_users with real data from your own database!
• Skim through Compose's core concepts to quickly become productive with the SDK.
• Join the Discord community to ask questions and talk to the core team.