BX 1.0

@dahura/bx is a Bun-first fullstack TypeScript framework. The published package is @dahura/[email protected]. BX 1.0 is the only canon. 0.3 is legacy.

One bx.app({ router, jobs, crons, workflows, … }) composition root lives on the server. The client never imports live handlers, the database, or secrets.

Install

Bun only. Pin the published line:

bun add @dahura/[email protected]

First product call

Install packaged Cursor rules and skills, then invoke Architect:

bunx --bun bx init --rules

In the product repo, run /bx-architect. Architect inspects the app, uses packaged grilling, maps behavior to BX 1.0, and routes to bx-pack (existing product onto client/ server/ generated/ deploy/), bx-compose, bx-routes, bx-bxdb, a shell skill, or bx-gates. It does not replace those skills.

Optional greenfield scaffold:

bunx --bun @dahura/[email protected] init --template react-bun --yes --rules

What 1.0 is

• Six exclusive route kinds: query, mutation, upload, workflow, stream (bx.sse), channel (bx.channel). Not bx.stream.
• Schema-first tables: bx.table / bx.db. Generated migrations. Do not hand-edit journal or snapshot metadata.
• Secrets as names: bx.secrets(({ secret }) => …). Never secret values in git, chat, logs, or manifests. No raw process.env in business or provider config.
• Client: createBXClient({ baseUrl, manifest }) from @dahura/bx/client plus the generated client-safe manifest. invalidates are BX route keys (todos/list), not page paths.
• Product tree: client/ · server/ · generated/ · deploy/. Client ≠ server. Do not hand-edit generated/.

| Shell | Adapter | HTTP prefix | Realtime | |-------|---------|-------------|----------| | React + Bun | bxPlugin from @dahura/bx | /bx | bx.sse and bx.channel | | Next.js App Router | createBXHandler from @dahura/bx/next | /api | bx.sse yes; bx.channel unsupported |

Public entries: @dahura/bx, @dahura/bx/client, @dahura/bx/server, @dahura/bx/next, @dahura/bx/db. There is no @dahura/bx/elysia.

Source of truth

Do not invent APIs. Read in this order:

1. AGENTS.md — 1.0 canon, gates, capability boundaries
2. dist/agent-knowledge/reference-manifest.json — shipped in the npm tarball; in this checkout run bun run build if it is missing
3. examples/todo-workspace — only reference app (README)

Todo Workspace is demo/local scope, not a production template. Shared router: examples/todo-workspace/shared/routes/app-router.ts. Shells: react-bun/ and next/. Copy patterns from there only.

App gates

From a product repo (not this monorepo’s maintainer scripts):

bx doctor --smoke --format json
bx check --format json
bx verify --profile fast --format json
# merge:
bx verify --profile ci --format json

License

MIT