Component Patterns

---
name: component-patterns
version: 2.0.0
description: Architecture patterns, code generation guides, and reference documentation for building Prismatic custom components.
user-invocable: false
---

# Component Patterns

Reference documentation for building Prismatic custom components.

<disallowed-tools>
Do NOT use these MCP tools — they return incomplete data that causes broken scaffolds and missing connections downstream. A hook will deny them, but avoid the wasted round trip.

- `mcp__prism__prism_components_list` — Use `run.ts find-components <keyword>` instead
- `mcp__prism__prism_components_init` — Use `run.ts scaffold-component` instead
- `mcp__prism__prism_components_publish` — Use `run.ts publish-component` instead
- `mcp__prism__prism_components_generate_manifest` — Manifests are auto-generated during scaffolding
- `mcp__prism__prism_install_component_manifest` — Handled by `run.ts scaffold-project --components`
- `mcp__prism__prism_install_legacy_component_manifest` — Handled by `run.ts scaffold-project --components`
</disallowed-tools>

## Architecture Patterns

### Connector Components
- Wrap external APIs (Salesforce, Canny, HubSpot, etc.)
- Support OAuth2, API Key, Bearer Token, Basic Auth
- Define connections, actions, triggers, and data sources
- Installed via Prism CLI

### Utility Components
- Provide helper actions (data transformation, formatting, etc.)
- No external connections needed
- Define only actions with typed inputs

## Config Mantra

Components define their own inputs — not `configVar()` wrappers. Each action uses `input()` definitions directly:
- `input()` for typed action inputs (label, type, required, comments, default)
- `connection()` for auth field definitions (key, label, inputs)
- Use `util.types` for input type constants
- See `references/authentication-patterns.md` for connection field patterns

## Phase: API Research

When the `on_answer` trigger fires for `api_docs_url`, the agent spawns the `external-api-researcher`
agent with the URL. The researcher fetches and analyzes the API docs, producing a structured JSON
spec at `{session_dir}/api-research.json`. The component builder waits for results before proceeding.

- See `references/api-research-guide.md` for the output format and research strategies
- Research results inform `auth_type`, `confirm_resources`, `webhook_support`, `base_url`

## Phase-Specific References

Load only the references relevant to your current workflow phase. This keeps context focused and avoids attention budget waste.

### Phase 2: Requirements Gathering
- Spec items carry `agent_context` (narration backbone), `implications` (per-option consequence maps), and `docs` (Prismatic doc URLs). The agent uses these inline — no external references needed for most questions. Docs are fetched on demand only when agent_context is insufficient or the user asks a follow-up beyond what the curated content covers.
- `references/api-research-guide.md` - How to research external APIs (load when `api_docs_url` is answered)

### Phase 3: Scaffold
- `references/component-architecture.md` - Component directory structure
- `references/spectral-component-quickstart.md` - Spectral SDK basics

### Phase 4: Code Generation (PRIMARY PHASE)
See the `<spec-loading>` block in component-builder.md for progressive disclosure rules.
The references below are the full set available — load per the agent's guidance.

- `references/answer-to-code-cookbook.md` - **LOAD FIRST** — Maps component.yaml answers directly to TypeScript code snippets. Spec items with `cookbook_section` fields point to specific headings in this file — Grep for those headings to find exact patterns, especially after context compaction.
- `references/code-generation-guide.md` - File generation patterns and component structure
- `references/authentication-patterns.md` - API Key, OAuth2, Bearer Token, Basic Auth patterns
- Templates: `${CLAUDE_PLUGIN_ROOT}/templates/component/` - Structural templates for all source files

**Conditional references for Phase 4 (load based on requirements):**
- If webhook triggers: `references/trigger-patterns.md` - Webhook trigger lifecycle and implementation
- If polling triggers: `references/trigger-patterns.md` - Polling trigger with `pollingTrigger()`, `context.polling` state management
- If OAuth2 auth: `references/oauth2-connection-guide.md` - Deep dive on OAuth2 connections (use `oauth2Connection()` from spectral, NOT `connection()`)
- If data sources: `references/data-source-patterns.md` - Data source implementation patterns
- Always for connectors: `references/client-patterns.md` - HTTP client helper patterns

### Phase 5: Build & Publish
- `references/troubleshooting-errors.md` - Build/publish failure solutions

### Examples (consult during code generation)
- `references/examples/utility-component/` - Complete utility example
- `references/examples/apikey-connector/` - Connector with API Key auth
- `references/examples/oauth2-connector/` - Connector with OAuth2 auth

## All References

Full reference list for manual lookup:
- `references/answer-to-code-cookbook.md` - Maps component.yaml answers to TypeScript code
- `references/api-research-guide.md` - How to research external APIs
- `references/component-architecture.md` - Component directory structure
- `references/code-generation-guide.md` - File generation patterns
- `references/authentication-patterns.md` - API Key and OAuth2 patterns
- `references/oauth2-connection-guide.md` - Deep dive on OAuth2 connections
- `references/spectral-component-quickstart.md` - Spectral SDK basics
- `references/trigger-patterns.md` - Webhook trigger lifecycle
- `references/data-source-patterns.md` - Data source patterns
- `references/client-patterns.md` - HTTP client helper patterns
- `references/troubleshooting-errors.md` - Build/publish failure solutions
- `references/examples/utility-component/` - Complete utility example
- `references/examples/apikey-connector/` - Connector with API Key auth
- `references/examples/oauth2-connector/` - Connector with OAuth2 auth

## Component Key Patterns

1. **Function-based client**: `createClient(connection, debug)` returning `HttpClient` from spectral — NOT class-based
2. **Error hook**: Every component MUST include `hooks: { error: (error) => { ... } }` — re-throw `ConnectionError` as-is, wrap others in `new Error()`
3. **rawRequest action**: REQUIRED in every component at `actions/misc/rawRequest.ts`
4. **Folder-based structure**: `actions/<resource>/`, `inputs/`, `examplePayloads/`, `dataSources/`, `triggers/`
5. **examplePayload**: Every action must have one, imported from `src/examplePayloads/`, verified against API
6. **Clean functions**: Every non-connection input needs `clean: util.types.toString` (or toBool, toNumber, etc.)
7. **Input requirements**: `comments`, `placeholder`, `example` on every string input
8. **Data source elements**: `{ label, key }` format (NOT `{ label, value }`) — type is `Element` from spectral
9. **Debug wiring**: `context.debug.enabled` → `createClient(connection, debug)` in actions, `false` in lifecycle hooks
10. **ConnectionError**: Thrown in client.ts for connection type mismatches, NOT in actions
11. **Webhook URL**: `context.webhookUrls[context.flow.name]` in lifecycle hooks
12. **Connection keys**: Simple names (`"apiKey"`, `"oauth2"`) — NOT `"component-api-key"`
13. **Action return**: Always `{ data: <result> }`. DataSource return: `{ result: Element[] }`