composurejs

---

A composurejs bot is a function from Request to Response. There is no gateway connection to keep alive, so the same App runs on Cloudflare Workers, Node and Bun, and you test it by calling it.

import { App, Button, command, Container, Row, Text } from "composurejs"

const Counter = ({ count, owner }: { count: number; owner: string }) => (
  <Container>
    <Text>## Count: {count}</Text>
    <Row>
      <Button onClick={(c) => (c.user.id === owner ? <Counter count={count + 1} owner={owner} /> : c.ephemeral("Not yours"))}>
        +1
      </Button>
    </Row>
  </Container>
)

export default new App().command(
  command({ name: "counter", description: "A counter", handler: (c) => <Counter count={0} owner={c.user.id} /> }),
)

The click handler lives on the button. There are no custom ids to invent and nothing to register: the Vite plugin hoists the handler, count and owner travel in the button's custom_id, and the markup the handler returns replaces the message.

Quick start

pnpm create composurejs my-bot

Pick Cloudflare Workers, Node or Bun, give it your development application and a test server, then pnpm dev. It serves the bot, opens a tunnel, points the application at it and syncs your Commands. Type /counter in Discord.

The getting started guide walks through it.

Features

• Commands typed from their definition. A Command's options type its handler's arguments, so the definition Discord sees and the code that runs can't drift apart. Subcommands, groups, context menu Commands, autocomplete and localizations included.
• JSX for messages. Every Components V2 and modal tag, checked against Discord's limits when it renders. A message that breaks a rule throws an error naming the rule, instead of Discord's "This interaction failed".
• Handlers inline. onClick, onSelect and onSubmit take a function wherever the component is. A Handler Lock catches a deploy that would break buttons already sent.
• Typed forms. Declare fields once, get parsed and typed modal values back.
• Middleware that guards buttons too. A Command's middleware also runs for the components it rendered. c.can(Permission.ManageMessages) for permission checks.
• Deferred responses. c.defer(async () => ...) for slow work, and Auto Defer for handlers that turn out slow.
• REST client. Endpoints typed from Discord's OpenAPI spec, with timeouts, retries and rate limit buckets. Each Endpoint is a function, so a bundle only keeps the ones it calls.
• One-command dev loop. vite dev tunnels to your machine, repoints your dev application, and re-syncs Commands to a test server on every save.
• Testing built in. composurejs/testing sends signed Interactions through the real pipeline and records what would have gone to Discord.
• Small. About 18 kB minified and brotlied for a Worker with Commands and JSX, zero runtime dependencies. CI fails the build past its size budget.

Runs on

Runtime	How
Cloudflare Workers	export default app, built with @cloudflare/vite-plugin
Node 22.12+	server() from @composurejs/vite builds a self-contained server
Bun	the same server build

// vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin"
import composure from "@composurejs/vite"
import { defineConfig } from "vite"

export default defineConfig({ plugins: [composure(), cloudflare()] })
// Node or Bun: plugins: [composure(), server()]

Testing

import { answer, chatInput } from "composurejs/testing"

test("the button counts", async () => {
  const first = await answer(app, chatInput("counter"))
  const next = await answer(app, first.click("+1"))
  expect(next.text).toContain("Count: 1")
})

Every request is signed with a real Ed25519 key and goes through the same pipeline as production. Nothing reaches Discord.

Packages

Package	Version
composurejs		The framework: App, Commands, JSX, REST, testing
@composurejs/vite		Compiles inline handlers, builds for each runtime, runs the dev loop
@composurejs/cli		composure sync: puts your Commands on Discord
@composurejs/eslint-plugin		Flags components placed where Discord won't accept them, for ESLint and oxlint
create-composurejs		pnpm create composurejs

Compared to discord-hono

discord-hono is also a Hono-like framework for Discord bots on Workers. composurejs differs in these ways:

• JSX with inline handlers, compiled by a Vite plugin (ADR 0015).
• One definition per Command types its handler and drives Sync.
• Explicit Apps that nest, so modules own their Commands (ADR 0001).
• Limits checked at render with errors that name the rule (ADR 0004).
• A dev loop that tunnels, repoints and syncs.
• Workers, Node and Bun over one pipeline, with no adapter packages (ADR 0024).

Status

composurejs is 0.x. It runs in production (this repo deploys its own bot), but the API may still change between minor versions. Changes are listed in each package's CHANGELOG and on the releases page.

It is a TypeScript port of the ideas in composure-rs.

Developing this repo

Path	What
packages/composurejs	Core and subpaths: /jsx-runtime, /components, /testing, /rest, /sync, /placement
packages/vite	composure() (inline handlers, the dev loop), server() (the Default Server)
packages/cli	composure sync (also a library)
packages/eslint-plugin	The placement rule
packages/create-composurejs	One template generator for every runtime
examples/bot	One App, built and run on workerd, Node and Bun by its tests
bots/composure	composurejs's own bot, deployed to Workers
docs	The guide (VitePress) and the ADRs
CONTEXT.md	The glossary

pnpm install
pnpm test        # builds the packages, then every workspace test
pnpm typecheck   # includes a Node-free check of core
pnpm size        # bundle budgets
pnpm -C docs dev # the guide

Developing needs Node 22.18+ and pnpm. See CONTRIBUTING.md for checks and releases.

License

Apache-2.0