# Macro Example Usage Scenarios and Demos: A Complete Guide > Explore macro-inc/macro with ready-to-run TypeScript SDK examples, interactive SolidJS demos, and Docker environments. Discover the platform's capabilities today. - Repository: [Macro/macro](https://github.com/macro-inc/macro) - Tags: getting-started - Published: 2026-08-15 --- **The macro-inc/macro repository ships with ready-to-run TypeScript SDK examples, interactive SolidJS UI demonstrations, and Docker-based local development environments to help developers explore the platform's capabilities.** The macro-inc/macro project provides comprehensive **example usage scenarios and demos** that illustrate core platform concepts and SDK integration patterns. These resources range from standalone scripts that interact with the API to embedded UI components within the onboarding flow. Developers can use these concrete implementations to understand real-time webhook handling, document manipulation, and frontend component architecture. ## TypeScript SDK Examples The `packages/sdk/examples/` directory contains executable scripts demonstrating how to build bots and automate workflows using the Macro SDK. ### Real-Time Webhook Event Handling The [`packages/sdk/examples/webhook-events.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/webhook-events.ts) file demonstrates how to register a webhook and listen to every Macro event. This script initializes a bot client, registers a webhook with a custom namespace, and sets up an event dispatcher that verifies webhook signatures. ```typescript // packages/sdk/examples/webhook-events.ts import { Macro } from '../src/macro'; const [url, actingUser] = process.argv.slice(2); const botToken = process.env.MACRO_BOT_TOKEN; if (!url || !actingUser || !botToken) { console.error( 'usage: MACRO_BOT_TOKEN=… bun examples/webhook-events.ts ', ); process.exit(1); } // Initialise a Macro client as a bot const macro = new Macro({ env: (process.env.MACRO_ENV ?? 'dev') as any, auth: { type: 'bot', token: botToken }, }).requestedAs(actingUser); // All supported events are enumerated in ALL_EVENTS const ALL_EVENTS = [ 'channel.created', 'channel.deleted', 'channel.message_posted', // … (see file for full list) ] as const; // Register the webhook const webhook = await macro.webhooks.create({ url, namespace: `sdk-webhook-demo-${crypto.randomUUID()}`, name: 'sdk webhook demo', filters: [{ events: [...ALL_EVENTS] }], }); const secret = webhook.signingSecret; // Set up an event dispatcher that verifies the signature const events = new Macro({ env: macro.env, auth: macro.auth, webhookSecret: secret, }).events; for (const name of ALL_EVENTS) { events.on(name, (e) => console.log(name, e.metadata)); } const receiver = events.webhook(); // <- returns an async request handler ``` Run this demo using **Bun**: ```bash MACRO_BOT_TOKEN=mbot_… bun examples/webhook-events.ts https://my‑public‑url.example.com ``` The script outputs each incoming event name and its metadata, providing a concise way to explore the full event payload surface. ### Document and Channel Operations Additional SDK examples include [`packages/sdk/examples/doc-dump.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/doc-dump.ts), which retrieves a document's JSON representation, and [`packages/sdk/examples/channel-probe.ts`](https://github.com/macro-inc/macro/blob/main/packages/sdk/examples/channel-probe.ts), which demonstrates fetching channel participants and recent messages. Both files instantiate the `Macro` class with bot authentication and showcase different API surface areas. ## Interactive SolidJS UI Demos The web application includes demo components that render UI primitives used throughout the onboarding flow. These live in `apps/web/src/lib/core/internal/` and demonstrate interactive patterns such as avatars, SVG noise grids, resize panels, and markdown mentions. ### Onboarding Lesson Demos The onboarding system embeds demo components directly into step-by-step walkthroughs. For example, [`apps/web/src/features/onboarding/lessons/markdown-mentions.tsx`](https://github.com/macro-inc/macro/blob/main/apps/web/src/features/onboarding/lessons/markdown-mentions.tsx) contains the `MarkdownMentionsDemo` component: ```tsx // apps/web/src/features/onboarding/lessons/markdown-mentions.tsx function MarkdownMentionsDemo(props: LessonContentProps) { // The demo renders a markdown editor with live @‑mention handling. // It is wired via the Macro “entity‑mention” service. const { editor, setEditor } = useMarkdownEditor(); return (
); } ``` The lesson exports a definition object that registers this component: ```tsx export const MarkdownMentionsLesson = { title: 'Markdown Mentions', definition: { // … demo: MarkdownMentionsDemo, }, }; ``` You can view this demo in the web UI by opening the onboarding modal (press `?` in the app) and selecting the "Markdown Mentions" lesson. Other internal demos like [`UserIconDemo.tsx`](https://github.com/macro-inc/macro/blob/main/UserIconDemo.tsx) showcase avatar primitives used across the application interface. ## Local Development Environment For developers wanting to explore the full stack, the repository includes Docker Compose configurations to spin up all required services. Create a complete local environment with: ```bash # From the repo root docker compose -f docker/docker-compose.yml up -d ``` This launches **PostgreSQL**, **Redis**, **OpenSearch**, and all microservices. Then initialize the database and run tests: ```bash just setup_macrodb # creates the main DB schema just test # runs the Rust test suite ``` Finally, start the web client to access the UI demos: ```bash cd apps/web pnpm install pnpm dev ``` This local instance provides access to all **example usage scenarios and demos** in a self-contained environment. ## Summary - The **TypeScript SDK** provides three main example scripts in `packages/sdk/examples/` for webhook handling, document inspection, and channel probing. - **SolidJS UI demos** are embedded throughout the web application, particularly in onboarding lessons under `apps/web/src/features/onboarding/lessons/`. - The **Docker Compose** setup in [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) enables full-stack local development with all backend services. - All demos instantiate the `Macro` class using bot authentication patterns and demonstrate production-ready integration techniques. ## Frequently Asked Questions ### How do I run the webhook events demo in the Macro repository? Execute the script using Bun with the required environment variables. Run `MACRO_BOT_TOKEN=mbot_… bun examples/webhook-events.ts ` from the `packages/sdk` directory. The script registers a webhook for all supported events and prints incoming payloads to the console. ### Where can I find UI demo components in the Macro codebase? UI demos reside in `apps/web/src/lib/core/internal/` and `apps/web/src/features/onboarding/lessons/`. Files like [`UserIconDemo.tsx`](https://github.com/macro-inc/macro/blob/main/UserIconDemo.tsx) and [`markdown-mentions.tsx`](https://github.com/macro-inc/macro/blob/main/markdown-mentions.tsx) contain interactive components used in the onboarding flow that you can view by pressing `?` in the web application. ### Does the Macro project include a local development environment? Yes. The repository includes [`docker/docker-compose.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose.yml) and [`docker/docker-compose-databases.yml`](https://github.com/macro-inc/macro/blob/main/docker/docker-compose-databases.yml) to launch PostgreSQL, Redis, OpenSearch, and all microservices. Use `just setup_macrodb` to initialize the schema and `pnpm dev` in `apps/web` to start the frontend with all demos enabled. ### What programming languages are used in the Macro examples? The SDK examples use **TypeScript** and run on the Bun runtime. The web demos use **SolidJS** (TypeScript/TSX) for UI components. The backend services referenced in the Docker Compose setup are primarily **Rust** based, as evidenced by the `just test` command running the Rust test suite.