# How Blocks Are Registered and Configured in the Sim Studio AI Block Registry

> Learn how Sim Studio AI registers and configures blocks in its registry. Discover type-safe lookup utilities for efficient block management in your AI projects.

- Repository: [Sim/sim](https://github.com/simstudioai/sim)
- Tags: internals
- Published: 2026-05-02

---

**The Sim Studio AI block registry maintains a centralized `Record<string, BlockConfig>` in [`apps/sim/blocks/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/registry.ts) that imports individual block definitions from `apps/sim/blocks/blocks/*.ts` and exposes type-safe lookup utilities including `getBlock()`, `getLatestBlock()`, and `getBlocksByCategory()`.**

The simstudioai/sim repository organizes workflow components through a strict registration pattern. Every block—whether it invokes an LLM or sends a Slack message—must be explicitly imported and mapped in the central registry to be recognized by the UI and execution engine. This design ensures type safety, discoverability, and runtime validation across the application.

## Importing Block Definitions

Block registration begins with static imports at the top of [`apps/sim/blocks/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/registry.ts) (lines 1–70). Each block resides in its own file under `apps/sim/blocks/blocks/` and exports a `BlockConfig` object:

```ts
import { OpenAIBlock } from '@/blocks/blocks/openai'
import { SlackBlock } from '@/blocks/blocks/slack'
import { GoogleSheetsBlock } from '@/blocks/blocks/google_sheets'

```

This explicit import pattern ensures that only declared blocks are included in the production bundle. The registry imports configurations for categories including **blocks**, **tools**, and **triggers**, establishing a complete inventory of available workflow nodes before the application initializes.

## Building the Central Registry Map

Following the imports, [`registry.ts`](https://github.com/simstudioai/sim/blob/main/registry.ts) constructs a `Record<string, BlockConfig>` named `registry` (lines 332–386). This object serves as the single source of truth for block resolution:

```ts
export const registry: Record<string, BlockConfig> = {
  openai: OpenAIBlock,
  slack: SlackBlock,
  google_sheets: GoogleSheetsBlock,
  // ...alphabetically sorted entries
}

```

**Keys** follow a strict lowercase snake_case convention (e.g., `google_sheets`, `openai`). **Values** contain the complete `BlockConfig` object including metadata, UI configuration, and tool definitions. This flat structure enables O(1) lookups while maintaining a deterministic alphabetical order for UI rendering.

## Registry Helper Utilities

[`registry.ts`](https://github.com/simstudioai/sim/blob/main/registry.ts) exports specialized functions to query the registry safely. These utilities abstract key normalization logic and filtering operations required by the React frontend and workflow executor.

**`getBlock(type)`** retrieves a configuration by string identifier, automatically normalizing hyphens to underscores (lines 488–494):

```ts
if (registry[type]) return registry[type]
const normalized = type.replace(/-/g, '_')
return registry[normalized]

```

**`getLatestBlock(baseType)`** resolves versioned block types (e.g., `openai_v1`, `openai_v2`) by filtering keys and sorting semantic versions (lines 496–511). This ensures workflows reference the most recent implementation when explicit versions are omitted.

**`getBlockByToolName(toolName)`** performs a reverse lookup from tool ID to block configuration (line 516). It searches the `tools.access` array of every registered block to find which block implements a specific tool capability.

**`getBlocksByCategory(category)`** filters the registry by top-level classification (line 520). Valid categories are `"blocks"`, `"tools"`, or `"triggers"`, enabling the toolbar to render grouped sections without hardcoding block lists.

**`isValidBlockType(type)`** performs existence checks with normalization (line 525), returning a boolean indicating whether a given string corresponds to a registered block.

## Block Configuration Structure

Every block file exports a `BlockConfig` object adhering to the interface declared in [`apps/sim/blocks/types.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/types.ts) (lines 38–74). This contract defines the shape required for registry inclusion:

```ts
export interface BlockConfig<T extends ToolResponse = ToolResponse> {
  type: string                          // Canonical identifier (e.g., "openai")
  name: string                          // Display name
  description: string
  category: BlockCategory                // "blocks" | "tools" | "triggers"
  bgColor: string
  icon: BlockIcon
  subBlocks: SubBlockConfig[]           // UI fields and auth inputs
  tools: {
    access: string[]                    // Associated tool IDs
    config?: { tool: (params) => string; params?: (params) => any }
  }
  inputs: Record<string, ParamConfig>
  outputs: Record<string, OutputFieldDefinition>
}

```

Concrete implementations populate these fields extensively. For example, `OpenAIBlock` in [`apps/sim/blocks/blocks/openai.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/blocks/openai.ts) specifies:

```ts
export const OpenAIBlock: BlockConfig = {
  type: 'openai',
  name: 'OpenAI',
  category: 'blocks',
  bgColor: '#FF6A00',
  subBlocks: [
    { id: 'model', title: 'Model', type: 'short-input', defaultValue: 'gpt-4' },
    { id: 'api_key', title: 'API Key', type: 'string', authMode: AuthMode.ApiKey }
  ],
  tools: {
    access: ['openai_completion'],
    config: { tool: (p) => `openai_${p.model}` }
  },
  inputs: { prompt: { type: 'string', description: 'Prompt text' } },
  outputs: { result: { type: 'string', description: 'Generated text' } }
}

```

This declarative pattern separates UI concerns (icons, colors) from execution logic (tool access, input/output schemas).

## Runtime Lookup Patterns

When rendering block pickers or executing workflows, the application imports helpers from [`registry.ts`](https://github.com/simstudioai/sim/blob/main/registry.ts) rather than accessing the raw `registry` object directly.

**Retrieving a block inside a React component:**

```tsx
import { getBlock } from '@/blocks/registry'
import { useEffect, useState } from 'react'

export function BlockInspector({ type }: { type: string }) {
  const [config, setConfig] = useState<BlockConfig | null>(null)

  useEffect(() => {
    setConfig(getBlock(type) || null)
  }, [type])

  if (!config) return <div>Unknown block type</div>
  return <div style={{ background: config.bgColor }}>{config.name}</div>
}

```

**Listing all available tool blocks:**

```ts
import { getBlocksByCategory } from '@/blocks/registry'

const tools = getBlocksByCategory('tools')
console.log('Available tools:', tools.map(b => b.type))
// Output: ['google_sheets', 'slack', ...]

```

**Resolving the latest versioned block:**

```ts
import { getLatestBlock } from '@/blocks/registry'

const latestConfig = getLatestBlock('openai')
if (latestConfig) {
  console.log(`Using ${latestConfig.type} with tools: ${latestConfig.tools.access}`)
}

```

## Summary

- The **Sim Studio AI block registry** resides in [`apps/sim/blocks/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/registry.ts) and exports a `Record<string, BlockConfig>` called `registry`.
- Individual block definitions are imported from `apps/sim/blocks/blocks/*.ts` and mapped using lowercase snake_case keys.
- **Helper utilities**—including `getBlock()`, `getLatestBlock()`, and `getBlocksByCategory()`—provide safe, normalized access patterns for UI and executor code.
- The **BlockConfig interface** in [`apps/sim/blocks/types.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/types.ts) (lines 38–74) enforces a strict contract requiring `type`, `category`, `tools`, `inputs`, and `outputs` declarations.
- Runtime lookups consume these utilities to resolve configurations from string identifiers, handling hyphen normalization and version resolution automatically.

## Frequently Asked Questions

### Where is the block registry file located in simstudioai/sim?

The registry is defined in [`apps/sim/blocks/registry.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/registry.ts). This file contains the central `registry` object (lines 332–386) and all exported lookup functions. It imports block configurations from the sibling `apps/sim/blocks/blocks/` directory.

### What fields are required in a BlockConfig for registration?

According to [`apps/sim/blocks/types.ts`](https://github.com/simstudioai/sim/blob/main/apps/sim/blocks/types.ts) (lines 38–74), a valid `BlockConfig` must include `type` (canonical string ID), `name` (display label), `description`, `category` (enum of "blocks", "tools", or "triggers"), `bgColor`, `icon`, `subBlocks` (UI configuration array), `tools` (access definitions), and `inputs`/`outputs` schemas. Optional fields include `integrationType`, `tags`, and version-specific flags.

### How does the registry handle hyphenated block type names?

The `getBlock()` function (lines 488–494) automatically normalizes hyphens to underscores. If you query `getBlock('open-ai')`, it first checks for an exact match, then falls back to checking `registry['open_ai']`. Similarly, `isValidBlockType()` (line 525) applies the same normalization logic before validation.

### How can I retrieve all blocks belonging to a specific category?

Use `getBlocksByCategory(category)` (line 520), which filters `Object.values(registry)` by the `category` property. Pass `"blocks"`, `"tools"`, or `"triggers"` to receive an array of matching `BlockConfig` objects suitable for rendering navigation panels or restricted selectors.