Frontend (React Package)

Relevant source files

• apps/cloud/src/mcp-session.e2e.node.test.ts
• e2e/desktop/traffic-light-overlap.test.ts
• packages/app/src/entry-client.tsx
• packages/app/src/web/shell.tsx
• packages/plugins/graphql/src/sdk/presets.ts
• packages/plugins/mcp/src/sdk/presets.ts
• packages/plugins/openapi/src/sdk/presets.ts
• packages/react/src/components/button.tsx
• packages/react/src/components/command-palette.tsx
• packages/react/src/components/filter-tabs.tsx
• packages/react/src/components/float-actions.tsx
• packages/react/src/components/integration-favicon.test.tsx
• packages/react/src/components/integration-favicon.tsx
• packages/react/src/components/spinner.tsx
• packages/react/src/components/textarea.tsx
• packages/react/src/components/wordmark.tsx
• packages/react/src/multiplayer/shell.tsx
• packages/react/src/styles/globals.css

The @executor-js/react package is the shared UI foundation for all Executor host environments (Desktop, Local, Cloud, and Self-Host). It provides a registry-grade minimal design system, a library of domain-specific React components, and the core "Console" dashboard used to manage integrations, tools, and policies.

Shared UI Architecture

The frontend is built on React, Tailwind CSS 4, and TanStack Router. State management is handled primarily via Effect atoms, which provide a reactive bridge between the UI and the underlying Executor SDK.

Design System and Styling

The design follows a "registry-grade" aesthetic, prioritizing high-contrast typography (Geist and Geist Mono) and minimal use of color packages/react/src/styles/globals.css52-55 It supports native-feeling experiences across platforms, including specific CSS overrides for the macOS Desktop app to handle frameless window controls (traffic lights) packages/react/src/styles/globals.css170-173

Multiplayer vs. Local Shells

The package provides two primary shell implementations:

• Local Shell: Used in apps/local and the Desktop app. It focuses on single-user, local-first management packages/app/src/web/shell.tsx155-160
• Multiplayer Shell: A provider-neutral shell used by Cloud and Self-Host environments. It abstracts identity via a shared useAuth() hook and supports organization switching packages/react/src/multiplayer/shell.tsx32-38

Code Entity Space Mapping

The following diagram illustrates how UI concepts map to specific code entities within the @executor-js/react package.

UI Component to Code Mapping

Sources: packages/react/src/multiplayer/shell.tsx50-55 packages/react/src/components/command-palette.tsx31-35 packages/react/src/components/wordmark.tsx11-14 packages/react/src/components/integration-favicon.tsx20-24

Core Features

Console Dashboard

The Console is the central hub for managing the Executor instance. It includes:

• Integrations List: A reactive list of connected sources (OpenAPI, MCP, GraphQL) powered by integrationsOptimisticAtom packages/app/src/web/shell.tsx101-105
• Navigation: Dynamic routing that handles organization-scoped paths (e.g., /{$orgSlug}/policies) packages/react/src/multiplayer/shell.tsx74-75
• Plugin Pages: Plugins can inject custom UI pages directly into the sidebar packages/app/src/web/shell.tsx61-66

For details on navigation and page structure, see Console UI Pages and Routing.

Integration Management

The library includes specialized components for registering new tool sources. It uses a "detection-first" approach where users provide a URL, and the system analyzes it to suggest the correct plugin (e.g., detecting an OpenAPI spec vs. an MCP endpoint) packages/react/src/components/command-palette.tsx115-120

For details on the registration lifecycle, see Integration Registration UI.

Component Library

A robust set of shared components tailored for developer tools:

• Command Palette: A ⌘K interface for navigating integrations and adding new sources packages/react/src/components/command-palette.tsx37-43
• Integration Favicons: A sophisticated resolution cascade that fetches icons from presets, local assets, or a dedicated logo proxy (integrations.sh) packages/react/src/components/integration-favicon.tsx180-186
• Wordmark: The standard product identity component packages/react/src/components/wordmark.tsx11-20

For details on individual components, see Shared UI Components.

Data Flow and State

State is managed using Effect Atoms, allowing the UI to reactively update when the underlying database or SDK state changes.

Frontend Data Flow

Sources: packages/app/src/web/shell.tsx7-10 packages/react/src/components/command-palette.tsx65-70 packages/app/src/web/shell.tsx102-105

Child Pages

• Console UI Pages and Routing: Detailed look at the TanStack Router configuration, organization-scoped routing, and the shared page templates for secrets, policies, and toolkits.
• Integration Registration UI: Technical breakdown of the Add*Source components, the MCP probe state machine, and the OAuth template editor.
• Shared UI Components: Documentation for the design system, Tailwind 4 configuration, and complex components like the Schema Explorer and Shiki-powered Code Blocks.

---

Sources:

• packages/app/src/web/shell.tsx7-151
• packages/react/src/multiplayer/shell.tsx32-140
• packages/react/src/styles/globals.css1-207
• packages/react/src/components/integration-favicon.tsx1-202
• packages/react/src/components/command-palette.tsx1-135
• packages/react/src/components/wordmark.tsx1-21