diff --git a/.changeset/wb-217-actions-hook.md b/.changeset/wb-217-actions-hook.md index 4e1f2eb9a..d9314b00c 100644 --- a/.changeset/wb-217-actions-hook.md +++ b/.changeset/wb-217-actions-hook.md @@ -2,4 +2,4 @@ '@workflowbuilder/sdk': minor --- -feat: add `useWorkflowBuilderActions()`. Gives custom layouts that omit `` imperative save / import / export / settings / read-only / theme / layout-direction actions. Also exports the `WorkflowBuilderActions`, `LayoutChangeOptions`, and `Theme` types. See [Custom layout without the app bar](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/#custom-layout-without-the-app-bar). +feat: add `useWorkflowBuilderActions()`. Gives custom layouts that omit `` imperative save / import / export / settings / read-only / theme / layout-direction actions. Also exports the `WorkflowBuilderActions`, `LayoutChangeOptions`, and `Theme` types. See [Custom toolbar without the app bar](https://www.workflowbuilder.io/docs/guides/configuring-the-editor/#custom-toolbar-without-the-app-bar). diff --git a/CLAUDE.md b/CLAUDE.md index d7c38d4a5..cc00acaec 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,25 +4,25 @@ Visual workflow editor SDK (React) with a reference backend and Temporal-based e ## Quick Reference -Three onboarding paths (A, B local-run; C docs-only). README "Get started" is the canonical guide for A and B. Path C ("Embed the SDK") lives in the [docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/) and has no local-stack commands. +Three onboarding paths (A installs from npm; B, C run the repo locally). README "Get started" covers all three. Path A ("Embed the SDK") installs `@workflowbuilder/sdk` from npm; the README has install + a minimal snippet, and the full guide lives in the [docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/). | Command | Path | What it does | | ---------------------------- | ---- | --------------------------------------------------------------------------- | -| `pnpm preflight` | both | Verify Node / pnpm / Docker / ports / `.env` files. Add `--json` for agents | -| `pnpm dev` / `pnpm dev:demo` | A | Demo (UI only, port 4200). No backend, no Docker | -| `pnpm infra:up` | B | Start Postgres + Temporal in Docker. Required before backend/worker | -| `pnpm -F backend db:migrate` | B | Apply Drizzle migrations. First run, or after schema changes | -| `pnpm dev:ai-studio` | B | Full stack: infra + backend (3001) + worker + AI Studio frontend (4201) | -| `pnpm dev:backend` | B | Backend only (debug). Needs infra up | -| `pnpm dev:worker` | B | Execution worker only (debug). Needs infra up | -| `pnpm infra:down` | B | Stop the Docker stack | +| `pnpm preflight` | B/C | Verify Node / pnpm / Docker / ports / `.env` files. Add `--json` for agents | +| `pnpm dev` / `pnpm dev:demo` | B | Demo (UI only, port 4200). No backend, no Docker | +| `pnpm infra:up` | C | Start Postgres + Temporal in Docker. Required before backend/worker | +| `pnpm -F backend db:migrate` | C | Apply Drizzle migrations. First run, or after schema changes | +| `pnpm dev:ai-studio` | C | Full stack: infra + backend (3001) + worker + AI Studio frontend (4201) | +| `pnpm dev:backend` | C | Backend only (debug). Needs infra up | +| `pnpm dev:worker` | C | Execution worker only (debug). Needs infra up | +| `pnpm infra:down` | C | Stop the Docker stack | | `pnpm dev:docs` | - | Docs site (Astro + Starlight) | | `pnpm build:lib` | - | Build the SDK package (`packages/sdk`) | | `pnpm build` | - | Build the demo app | | `pnpm test` | - | Run tests in `packages/sdk` and `packages/execution-core` | | `pnpm check` | - | Lint + typecheck + format + knip | -Path A is UI-only and does not need Docker. Path B requires `pnpm infra:up` before backend/worker can start, and `db:migrate` on the first run. +Path B is UI-only and does not need Docker. Path C requires `pnpm infra:up` before backend/worker can start, and `db:migrate` on the first run. ### Agent signals @@ -123,7 +123,7 @@ If you're new to this repo and want to build your own consumer app or POC, follo | `/wb.create-plugin ` | Scaffold a new SDK plugin — asks for target app (default `demo`) | | `/wb.create-template ` | Scaffold a new diagram template — asks for target app (default `demo`) | | `/wb.add-execution-handler ` | Wire a node type into execution-core + worker registry (global pipeline, no target) | -| `/wb.run-locally` | Bring up the stack — Path A (`pnpm dev:demo`) or Path B (infra + backend + worker + AI Studio frontend) | +| `/wb.run-locally` | Bring up the stack — Path B (`pnpm dev:demo`) or Path C (infra + backend + worker + AI Studio frontend) | | `/wb.task` | Fetch assigned ClickUp tasks via MCP and recommend one to pick up | | `/wb.task WB-42` | Pick up a specific task with an inline plan | | `/wb.changeset ""` | Add a changeset for SDK changes (`patch` / `minor` / `major`) — required before merging consumer-visible changes to `packages/sdk/**` | diff --git a/README.md b/README.md index fd8188563..3b8ad4e2e 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Workflow Builder -[Live Demo](https://app.workflowbuilder.io/)  |  [Documentation](https://www.workflowbuilder.io/docs/overview/)  |  [Website](https://www.workflowbuilder.io/) +[Live Demo](https://app.workflowbuilder.io/)  |  [Documentation](https://www.workflowbuilder.io/docs/overview/)  |  [npm](https://www.npmjs.com/package/@workflowbuilder/sdk)  |  [Website](https://www.workflowbuilder.io/) **Workflow Builder** @@ -38,16 +38,47 @@ Three onboarding paths. Pick one based on what you want to evaluate. | Goal | Path | Setup time | Docker | | ------------------------------------------------------ | ------------------------------------------------------------- | ---------- | ------ | -| See the editor running in your browser | [A. Try the demo](#path-a-try-the-demo) | ~2 min | no | -| Run the full reference stack (editor + execution + AI) | [B. Run the full stack demo](#path-b-run-the-full-stack-demo) | ~10 min | yes | -| Use the SDK inside your own React app | [C. Embed the SDK](#path-c-embed-the-sdk) | see docs | no | +| Use the SDK inside your own React app | [A. Embed the SDK](#path-a-embed-the-sdk) | ~1 min | no | +| See the editor running in your browser | [B. Try the demo](#path-b-try-the-demo) | ~2 min | no | +| Run the full reference stack (editor + execution + AI) | [C. Run the full stack demo](#path-c-run-the-full-stack-demo) | ~10 min | yes | -Want to skip the clone entirely? [Try the live demo](https://app.workflowbuilder.io) first. +Don't want to install or clone anything yet? [Try the live demo](https://app.workflowbuilder.io) in your browser first. + +### Path A. Embed the SDK + +Use Workflow Builder inside your own React app. No clone, no Docker. Install the SDK and its peer dependencies from npm: + +```bash +npm install @workflowbuilder/sdk \ + react react-dom \ + @xyflow/react \ + @jsonforms/core @jsonforms/react \ + i18next react-i18next i18next-browser-languagedetector \ + immer zustand +``` + +Render the editor: + +```tsx +import { WorkflowBuilder } from '@workflowbuilder/sdk'; + +import '@workflowbuilder/sdk/style.css'; + +export function App() { + return ; +} +``` + +It mounts the default layout (top bar, palette, canvas, properties panel) and persists to `localStorage` out of the box. The palette is empty until you pass `nodeTypes`. + +Full guide (props, persistence strategies, theming, plugins, and the API reference): [React Component on the docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/). + +The two paths below run this repository locally (demo and full stack). They share the requirements and preflight check that follow. Path A needs neither. ### Requirements - Node `22.12.0` and pnpm `10.9.0`. Both pinned in `package.json`. Use `nvm`, `fnm`, or `corepack` to match. -- Docker Desktop. Only required for Path B. +- Docker Desktop. Only required for Path C. Works the same on macOS, Linux, and Windows. No platform-specific steps. @@ -81,11 +112,11 @@ Workflow Builder preflight Ready to go. Pick a path in README.md "Get started". ``` -The two `.env` warnings are expected on a fresh clone. They are only required for Path B and get created by `pnpm setup:env` in step 1 of that path. After that they switch to `✅ present`. +The two `.env` warnings are expected on a fresh clone. They are only required for Path C and get created by `pnpm setup:env` in step 1 of that path. After that they switch to `✅ present`. Fix any red (`❌`) items before continuing. The script also has a `--json` mode for tooling: `pnpm preflight --json`. -### Path A. Try the demo +### Path B. Try the demo UI only. No backend, no Docker. The fastest way to see the editor in action. @@ -104,7 +135,7 @@ Expected output: Open `http://localhost:4200`. The editor loads with the default plugin set and a starter template. That's it. -### Path B. Run the full stack demo +### Path C. Run the full stack demo Full reference product: editor, Hono backend, Temporal worker, Postgres. The frontend on port 4201 is the **AI Studio** reference product (`apps/ai-studio`). Demonstrates end-to-end workflow execution. @@ -180,10 +211,6 @@ AI_MODEL=anthropic/claude-3.5-haiku If the key is missing the worker fails to start with `OPENROUTER_API_KEY is required`. If the model id is wrong the first AI node fails at runtime and the error surfaces in the UI log panel. -### Path C. Embed the SDK - -To build your own React app on top of `@workflowbuilder/sdk`, follow the [React Component guide on the docs site](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/). It covers installation, peer deduplication (for local-path builds until npm publish), usage, persistence strategies, theming, and the full API reference. - ### Troubleshooting | Symptom | Cause | Fix | diff --git a/apps/ai-studio/README.md b/apps/ai-studio/README.md index cdcb92b32..383877afe 100644 --- a/apps/ai-studio/README.md +++ b/apps/ai-studio/README.md @@ -4,7 +4,7 @@ Reference frontend for the Workflow Builder AI Studio product. Consumes `@workfl > ⚠️ Local development only. Depends on the reference backend, which has no auth/authz. See [apps/backend/README.md](../backend/README.md). -> **Note:** setup is in [root README "Path B. Run the full stack demo"](../../README.md#path-b-run-the-full-stack-demo). +> **Note:** setup is in [root README "Path C. Run the full stack demo"](../../README.md#path-c-run-the-full-stack-demo). ## What this is diff --git a/apps/backend/README.md b/apps/backend/README.md index b430cac55..018180252 100644 --- a/apps/backend/README.md +++ b/apps/backend/README.md @@ -5,7 +5,7 @@ > > Seams for consumers to plug in: [`AuthPort`](./auth-port.decision-log.md) for authn/authz, [`TenantContextPort`](./tenant-context-port.decision-log.md) for multi-tenant identity propagation (wiring guide: [`multi-tenancy.md`](./multi-tenancy.md)). -> **Note:** setup is in [root README "Path B. Run the full stack demo"](../../README.md#path-b-run-the-full-stack-demo). This file documents the backend's internals, not how to start it. +> **Note:** setup is in [root README "Path C. Run the full stack demo"](../../README.md#path-c-run-the-full-stack-demo). This file documents the backend's internals, not how to start it. Backend execution layer for Workflow Builder AI Studio plugin. Runs AI workflows defined on the canvas via Temporal + OpenRouter. diff --git a/apps/execution-worker/README.md b/apps/execution-worker/README.md index dae58e0e3..4ac25dd11 100644 --- a/apps/execution-worker/README.md +++ b/apps/execution-worker/README.md @@ -1,6 +1,6 @@ # @workflow-builder/execution-worker -> **Note:** setup is in [root README "Path B. Run the full stack demo"](../../README.md#path-b-run-the-full-stack-demo). This file documents the worker's internals. +> **Note:** setup is in [root README "Path C. Run the full stack demo"](../../README.md#path-c-run-the-full-stack-demo). This file documents the worker's internals. Background process that executes workflow graphs submitted by the backend. Currently backed by Temporal; structured so other engines (in-memory, BullMQ, …) can slot in without touching domain logic. diff --git a/packages/sdk/src/features/integration/README.md b/packages/sdk/src/features/integration/README.md index d3b52c2a7..7d03bfdea 100644 --- a/packages/sdk/src/features/integration/README.md +++ b/packages/sdk/src/features/integration/README.md @@ -16,7 +16,7 @@ By default, Workflow Builder is a standalone app. You can build the application Workflow Builder can function as a component within an existing React application. This allows you to integrate its functionality directly into your app rather than hosting it separately. -How to embed Workflow Builder in an existing React codebase: see the [React component quick-start](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/), which covers installation, peer deduplication (local-path build until npm publish), usage, and configuration. +How to embed Workflow Builder in an existing React codebase: see the [React component quick-start](https://www.workflowbuilder.io/docs/get-started/quick-start/wb-as-react-component/), which covers installation from npm, usage, and configuration. You can also build your application as an npm package and then simply consume it in your application.