Repository: simstudioai/sim

Stars: 27814

CLAUDE.md

Sim Development Guidelines

You are a professional software engineer. All code must follow best practices: accurate, readable, clean, and efficient.

Global Standards

- Logging: Import createLogger from @sim/logger. Use logger.info, logger.warn, logger.error instead of console.log
- Comments: Use TSDoc for documentation. No ==== separators. No non-TSDoc comments
- Styling: Never update global styles. Keep all styling local to components
- ID Generation: Never use crypto.randomUUID(), nanoid, or uuid package. Use generateId() (UUID v4) or generateShortId() (compact) from @/lib/core/utils/uuid
- Package Manager: Use bun and bunx, not npm and npx

Architecture

Core Principles

1. Single Responsibility: Each component, hook, store has one clear purpose
2. Composition Over Complexity: Break down complex logic into smaller pieces
3. Type Safety First: TypeScript interfaces for all props, state, return types
4. Predictable State: Zustand for global state, useState for UI-only concerns

Root Structure

text

apps/sim/
├── app/           # Next.js app router (pages, API routes)
├── blocks/        # Block definitions and registry
├── components/    # Shared UI (emcn/, ui/)
├── executor/      # Workflow execution engine
├── hooks/         # Shared hooks (queries/, selectors/)
├── lib/           # App-wide utilities
├── providers/     # LLM provider integrations
├── stores/        # Zustand stores
├── tools/         # Tool definitions
└── triggers/      # Trigger definitions

Naming Conventions

- Components: PascalCase (WorkflowList)
- Hooks: use prefix (useWorkflowOperations)
- Files: kebab-case (workflow-list.tsx)
- Stores: stores/feature/store.ts
- Constants: SCREAMING_SNAKE_CASE
- Interfaces: PascalCase with suffix (WorkflowListProps)

Imports

Always use absolute imports. Never use relative imports.

typescript

// ✓ Good
import { useWorkflowStore } from '@/stores/workflows/store'// ✗ Bad
import { useWorkflowStore } from '../../../stores/workflows/store'

Use barrel exports (index.ts) when a folder has 3+ exports. Do not re-export from non-barrel files; import directly from the source.

Import Order

1. React/core libraries
2. External libraries
3. UI components (@/components/emcn, @/components/ui)
4. Utilities (@/lib/...)
5. Stores (@/stores/...)
6. Feature imports
7. CSS imports

Use import type { X } for type-only imports.

TypeScript

1. No any - Use proper types or unknown with type guards
2. Always define props interface for components
3. as const for constant objects/arrays
4. Explicit ref types: useRef<HTMLDivElement>(null)

Components

typescript

'use client' // Only if using hooks
const CONFIG = { SPACING: 8 } as const
interface ComponentProps {
  requiredProp: string
  optionalProp?: boolean
}export function Component({ requiredProp, optionalProp = false }: ComponentProps) {
  // Order: refs → external hooks → store hooks → custom hooks → state → useMemo → useCallback → useEffect → return
}

Extract when: 50+ lines, used in 2+ files, or has own state/logic. Keep inline when: < 10 lines, single use, purely presentational.

Hooks

typescript

interface UseFeatureProps { id: string }export function useFeature({ id }: UseFeatureProps) {
  const idRef = useRef(id)
  const [data, setData] = useState<Data | null>(null)
  
  useEffect(() => { idRef.current = id }, [id])
  
  const fetchData = useCallback(async () => { ... }, []) // Empty deps when using refs
  
  return { data, fetchData }
}

Zustand Stores

Stores live in stores/. Complex stores split into store.ts + types.ts.

typescript

import { create } from 'zustand'
import { devtools } from 'zustand/middleware'
const initialState = { items: [] as Item[] }export const useFeatureStore = create<FeatureState>()(
  devtools(
    (set, get) => ({
      ...initialState,
      setItems: (items) => set({ items }),
      reset: () => set(initialState),
    }),
    { name: 'feature-store' }
  )
)

Use devtools middleware. Use persist only when data should survive reload with partialize to persist only necessary state.

React Query

All React Query hooks live in hooks/queries/. All server state must go through React Query — never use useState + fetch in components for data fetching or mutations.

Query Key Factory

Every file must have a hierarchical key factory with an all root key and intermediate plural keys for prefix invalidation:

typescript

export const entityKeys = {
  all: ['entity'] as const,
  lists: () => [...entityKeys.all, 'list'] as const,
  list: (workspaceId?: string) => [...entityKeys.lists(), workspaceId ?? ''] as const,
  details: () => [...entityKeys.all, 'detail'] as const,
  detail: (id?: string) => [...entityKeys.details(), id ?? ''] as const,
}

Query Hooks

- Every queryFn must forward signal for request cancellation
- Every query must have an explicit staleTime
- Use keepPreviousData only on variable-key queries (where params change), never on static keys

typescript

export function useEntityList(workspaceId?: string) {
  return useQuery({
    queryKey: entityKeys.list(workspaceId),
    queryFn: ({ signal }) => fetchEntities(workspaceId as string, signal),
    enabled: Boolean(workspaceId),
    staleTime: 60 * 1000,
    placeholderData: keepPreviousData, // OK: workspaceId varies
  })
}

Mutation Hooks

- Use targeted invalidation (entityKeys.lists()) not broad (entityKeys.all) when possible
- For optimistic updates: use onSettled (not onSuccess) for cache reconciliation — onSettled fires on both success and error
- Don't include mutation objects in useCallback deps — .mutate() is stable in TanStack Query v5

typescript

export function useUpdateEntity() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: async (variables) => { / ... / },
    onMutate: async (variables) => {
      await queryClient.cancelQueries({ queryKey: entityKeys.detail(variables.id) })
      const previous = queryClient.getQueryData(entityKeys.detail(variables.id))
      queryClient.setQueryData(entityKeys.detail(variables.id), / optimistic /)
      return { previous }
    },
    onError: (_err, variables, context) => {
      queryClient.setQueryData(entityKeys.detail(variables.id), context?.previous)
    },
    onSettled: (_data, _error, variables) => {
      queryClient.invalidateQueries({ queryKey: entityKeys.lists() })
      queryClient.invalidateQueries({ queryKey: entityKeys.detail(variables.id) })
    },
  })
}

Styling

Use Tailwind only, no inline styles. Use cn() from @/lib/utils for conditional classes.

typescript

<div className={cn('base-classes', isActive && 'active-classes')} />

EMCN Components

Import from @/components/emcn, never from subpaths (except CSS files). Use CVA when 2+ variants exist.

Testing

Use Vitest. Test files: feature.ts → feature.test.ts. See .cursor/rules/sim-testing.mdc for full details.

Global Mocks (vitest.setup.ts)

@sim/db, drizzle-orm, @sim/logger, @/blocks/registry, @trigger.dev/sdk, and store mocks are provided globally. Do NOT re-mock them unless overriding behavior.

Standard Test Pattern

typescript

/
 * @vitest-environment node
 */
import { createMockRequest } from '@sim/testing'
import { beforeEach, describe, expect, it, vi } from 'vitest'
const { mockGetSession } = vi.hoisted(() => ({
  mockGetSession: vi.fn(),
}))
vi.mock('@/lib/auth', () => ({
  auth: { api: { getSession: vi.fn() } },
  getSession: mockGetSession,
}))
import { GET } from '@/app/api/my-route/route'describe('my route', () => {
  beforeEach(() => {
    vi.clearAllMocks()
    mockGetSession.mockResolvedValue({ user: { id: 'user-1' } })
  })
  it('returns data', async () => { ... })
})

Performance Rules

- NEVER use vi.resetModules() + vi.doMock() + await import() — use vi.hoisted() + vi.mock() + static imports
- NEVER use vi.importActual() — mock everything explicitly
- NEVER use mockAuth(), mockConsoleLogger(), setupCommonApiMocks() from @sim/testing — they use vi.doMock() internally
- Mock heavy deps (@/blocks, @/tools/registry, @/triggers) in tests that don't need them
- Use @vitest-environment node unless DOM APIs are needed (window, document, FormData)
- Avoid real timers — use 1ms delays or vi.useFakeTimers()

Use @sim/testing mocks/factories over local test data.

Utils Rules

- Never create utils.ts for single consumer - inline it
- Create utils.ts when 2+ files need the same helper
- Check existing sources in lib/ before duplicating

Adding Integrations

New integrations require: Tools → Block → Icon → (optional) Trigger

Always look up the service's API docs first.

1. Tools (`tools/{service}/`)

text

tools/{service}/
├── index.ts      # Barrel export
├── types.ts      # Params/response types
└── {action}.ts   # Tool implementation

Tool structure:

typescript

export const serviceTool: ToolConfig<Params, Response> = {
  id: 'service_action',
  name: 'Service Action',
  description: '...',
  version: '1.0.0',
  oauth: { required: true, provider: 'service' },
  params: { / ... / },
  request: { url: '/api/tools/service/action', method: 'POST', ... },
  transformResponse: async (response) => { / ... / },
  outputs: { / ... / },
}

2. Block (`blocks/blocks/{service}.ts`)

typescript

export const ServiceBlock: BlockConfig = {
  type: 'service',
  name: 'Service',
  description: '...',
  category: 'tools',
  bgColor: '#hexcolor',
  icon: ServiceIcon,
  subBlocks: [ / see SubBlock Properties / ],
  tools: { access: ['service_action'], config: { tool: (p) => service_${p.operation}, params: (p) => ({ / type coercions here / }) } },
  inputs: { / ... / },
  outputs: { / ... / },
}

Important: tools.config.tool runs during serialization (before variable resolution). Never do Number() or other type coercions there — dynamic references like <Block.output> will be destroyed. Use tools.config.params for type coercions (it runs during execution, after variables are resolved).

SubBlock Properties:

typescript

{
  id: 'field', title: 'Label', type: 'short-input', placeholder: '...',
  required: true,                    // or condition object
  condition: { field: 'op', value: 'send' },  // show/hide
  dependsOn: ['credential'],         // clear when dep changes
  mode: 'basic',                     // 'basic' | 'advanced' | 'both' | 'trigger'
}

condition examples:
- { field: 'op', value: 'send' } - show when op === 'send'
- { field: 'op', value: ['a','b'] } - show when op is 'a' OR 'b'
- { field: 'op', value: 'x', not: true } - show when op !== 'x'
- { field: 'op', value: 'x', not: true, and: { field: 'type', value: 'dm', not: true } } - complex

dependsOn: ['field'] or { all: ['a'], any: ['b', 'c'] }

File Input Pattern (basic/advanced mode):

typescript

// Basic: file-upload UI
{ id: 'uploadFile', type: 'file-upload', canonicalParamId: 'file', mode: 'basic' },
// Advanced: reference from other blocks
{ id: 'fileRef', type: 'short-input', canonicalParamId: 'file', mode: 'advanced' },

In tools.config.tool, normalize with:

typescript

import { normalizeFileInput } from '@/blocks/utils'
const file = normalizeFileInput(params.uploadFile || params.fileRef, { single: true })
if (file) params.file = file

For file uploads, create an internal API route (/api/tools/{service}/upload) that uses downloadFileFromStorage to get file content from UserFile objects.

3. Icon (`components/icons.tsx`)

typescript

export function ServiceIcon(props: SVGProps<SVGSVGElement>) {
  return <svg {...props}>/ SVG from brand assets /</svg>
}

4. Trigger (`triggers/{service}/`) - Optional

text

triggers/{service}/
├── index.ts      # Barrel export
├── webhook.ts    # Webhook handler
└── {event}.ts    # Event-specific handlers

Integration Checklist

- [ ] Look up API docs
- [ ] Create tools/{service}/ with types and tools
- [ ] Register tools in tools/registry.ts
- [ ] Add icon to components/icons.tsx
- [ ] Create block in blocks/blocks/{service}.ts
- [ ] Register block in blocks/registry.ts
- [ ] (Optional) Create and register triggers
- [ ] (If file uploads) Create internal API route with downloadFileFromStorage
- [ ] (If file uploads) Use normalizeFileInput in block config

README.md

The open-source platform to build AI agents and run your agentic workforce. Connect 1,000+ integrations and LLMs to orchestrate agentic workflows.

Build Workflows with Ease

Design agent workflows visually on a canvas—connect agents, tools, and blocks, then run them instantly.

Supercharge with Copilot

Leverage Copilot to generate nodes, fix errors, and iterate on flows directly from natural language.

Integrate Vector Databases

Upload documents to a vector store and let agents answer questions grounded in your specific content.

Quickstart

Cloud-hosted: sim.ai

Self-hosted: NPM Package

bash

npx simstudio

→ http://localhost:3000

#### Note
Docker must be installed and running on your machine.

#### Options

| Flag | Description |
|------|-------------|
| -p, --port <port> | Port to run Sim on (default 3000) |
| --no-pull | Skip pulling latest Docker images |

Self-hosted: Docker Compose

bash

git clone https://github.com/simstudioai/sim.git && cd sim
docker compose -f docker-compose.prod.yml up -d

Open http://localhost:3000

Sim also supports local models via Ollama and vLLM — see the Docker self-hosting docs for setup details.

Self-hosted: Manual Setup

Requirements: Bun, Node.js v20+, PostgreSQL 12+ with pgvector

1. Clone and install:

bash

git clone https://github.com/simstudioai/sim.git
cd sim
bun install
bun run prepare  # Set up pre-commit hooks

2. Set up PostgreSQL with pgvector:

bash

docker run --name simstudio-db -e POSTGRES_PASSWORD=your_password -e POSTGRES_DB=simstudio -p 5432:5432 -d pgvector/pgvector:pg17

Or install manually via the pgvector guide.

3. Configure environment:

bash

cp apps/sim/.env.example apps/sim/.env
Create your secrets

perl -i -pe "s/your_encryption_key/$(openssl rand -hex 32)/" apps/sim/.env
perl -i -pe "s/your_internal_api_secret/$(openssl rand -hex 32)/" apps/sim/.env
perl -i -pe "s/your_api_encryption_key/$(openssl rand -hex 32)/" apps/sim/.env
DB configs for migration

cp packages/db/.env.example packages/db/.env
Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"

4. Run migrations:

bash

cd packages/db && bun run db:migrate

5. Start development servers:

bash

bun run dev:full  # Starts Next.js app and realtime socket server

Or run separately: bun run dev (Next.js) and cd apps/sim && bun run dev:sockets (realtime).

Copilot API Keys

Copilot is a Sim-managed service. To use Copilot on a self-hosted instance:

- Go to https://sim.ai → Settings → Copilot and generate a Copilot API key
- Set COPILOT_API_KEY environment variable in your self-hosted apps/sim/.env file to that value

Environment Variables

See the environment variables reference for the full list, or apps/sim/.env.example for defaults.

Tech Stack

- Framework: Next.js (App Router)
- Runtime: Bun
- Database: PostgreSQL with Drizzle ORM
- Authentication: Better Auth
- UI: Shadcn, Tailwind CSS
- State Management: Zustand
- Flow Editor: ReactFlow
- Docs: Fumadocs
- Monorepo: Turborepo
- Realtime: Socket.io
- Background Jobs: Trigger.dev
- Remote Code Execution: E2B

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Made with ❤️ by the Sim Team

Repository: simstudioai/sim

Stars: 27814

CLAUDE.md Copy Chapter

Sim Development Guidelines

Global Standards Copy Chapter

Architecture Copy Chapter

Core Principles Copy Section

Root Structure Copy Section

Naming Conventions Copy Section

Imports Copy Chapter

Import Order Copy Section

TypeScript Copy Chapter

Components Copy Chapter

Hooks Copy Chapter

Zustand Stores Copy Chapter

React Query Copy Chapter

Query Key Factory Copy Section

Query Hooks Copy Section

Mutation Hooks Copy Section

Styling Copy Chapter

EMCN Components Copy Chapter

Testing Copy Chapter

Global Mocks (vitest.setup.ts) Copy Section

Standard Test Pattern Copy Section

Performance Rules Copy Section

Utils Rules Copy Chapter

Adding Integrations Copy Chapter

1. Tools (tools/{service}/) tools/{service}/)')" title="Copy section prompt for LLMs"> Copy Section

2. Block (blocks/blocks/{service}.ts) blocks/blocks/{service}.ts)')" title="Copy section prompt for LLMs"> Copy Section

3. Icon (components/icons.tsx) components/icons.tsx)')" title="Copy section prompt for LLMs"> Copy Section

4. Trigger (triggers/{service}/) - Optional triggers/{service}/) - Optional')" title="Copy section prompt for LLMs"> Copy Section

Integration Checklist Copy Section

README.md Copy Chapter

Build Workflows with Ease Copy Section

Supercharge with Copilot Copy Section

Integrate Vector Databases Copy Section

Quickstart Copy Chapter

Cloud-hosted: sim.ai sim.ai')" title="Copy section prompt for LLMs"> Copy Section

Self-hosted: NPM Package Copy Section

Self-hosted: Docker Compose Copy Section

Self-hosted: Manual Setup Copy Section

Create your secrets

DB configs for migration

Edit both .env files to set DATABASE_URL="postgresql://postgres:your_password@localhost:5432/simstudio"

Copilot API Keys Copy Chapter

Environment Variables Copy Chapter

Tech Stack Copy Chapter

Contributing Copy Chapter

License Copy Chapter

CLAUDE.md

Global Standards

Architecture

Core Principles

Root Structure

Naming Conventions

Imports

Import Order

TypeScript

Components

Hooks

Zustand Stores

React Query

Query Key Factory

Query Hooks

Mutation Hooks

Styling

EMCN Components

Testing

Global Mocks (vitest.setup.ts)

Standard Test Pattern

Performance Rules

Utils Rules

Adding Integrations

1. Tools (`tools/{service}/`)

2. Block (`blocks/blocks/{service}.ts`)

3. Icon (`components/icons.tsx`)

4. Trigger (`triggers/{service}/`) - Optional

Integration Checklist

README.md

Build Workflows with Ease

Supercharge with Copilot

Integrate Vector Databases

Quickstart

Cloud-hosted: sim.ai

Self-hosted: NPM Package

Self-hosted: Docker Compose

Self-hosted: Manual Setup

Copilot API Keys

Environment Variables

Tech Stack

Contributing

License