github/sim

mirror of https://github.com/simstudioai/sim.git synced 2026-01-09 15:07:55 -05:00

Files

Waleed Latif 60ee86c71d docs: updated docker + README to reflect new monorepo structure, removed husky

2025-03-13 16:33:14 -07:00

14 KiB

Raw Blame History

Contributing to Sim Studio

Thank you for your interest in contributing to Sim Studio! Our goal is to provide developers with a powerful, user-friendly platform for building, testing, and optimizing agentic workflows. We welcome contributions in all forms—from bug fixes and design improvements to brand-new features.

Project Overview:
Sim Studio is a monorepo containing the main application (sim/) and documentation (docs/). The main application is built with Next.js (app router), ReactFlow, Zustand, Shadcn, and Tailwind CSS. Please ensure your contributions follow our best practices for clarity, maintainability, and consistency.

How to Contribute
Reporting Issues
Pull Request Process
Commit Message Guidelines
Local Development Setup
License
Adding New Blocks and Tools
Local Storage Mode
Standalone Build

How to Contribute

We strive to keep our workflow as simple as possible. To contribute:

Fork the Repository
Click the Fork button on GitHub to create your own copy of the project.

Clone Your Fork

git clone https://github.com/<your-username>/sim.git

Create a Feature Branch
Create a new branch with a descriptive name:
```
git checkout -b feat/your-feature-name
```
Use a clear naming convention to indicate the type of work (e.g., feat/, fix/, docs/).
Make Your Changes
Ensure your changes are small, focused, and adhere to our coding guidelines.
Commit Your Changes
Write clear, descriptive commit messages that follow the Conventional Commits specification. This allows us to maintain a coherent project history and generate changelogs automatically. For example:
- feat(api): add new endpoint for user authentication
- fix(ui): resolve button alignment issue
- docs: update contribution guidelines
Push Your Branch
```
git push origin feat/your-feature-name
```
Create a Pull Request
Open a pull request against the main branch on GitHub. Please provide a clear description of the changes and reference any relevant issues (e.g., fixes #123).

Reporting Issues

If you discover a bug or have a feature request, please open an issue in our GitHub repository. When opening an issue, ensure you:

Provide a clear, descriptive title.
Include as many details as possible (steps to reproduce, screenshots, etc.).
Tag Your Issue Appropriately:
Use the following labels to help us categorize your issue:
- active: Actively working on it right now.
- bug: Something isn't working.
- design: Improvements & changes to design & UX.
- discussion: Initiate a discussion or propose an idea.
- documentation: Improvements or updates to documentation.
- feature: New feature or request.

Note: If you're uncertain which label to use, mention it in your issue description and we'll help categorize it.

Pull Request Process

Before creating a pull request:

Ensure Your Branch Is Up-to-Date:
Rebase your branch onto the latest main branch to prevent merge conflicts.
Follow the Guidelines:
Make sure your changes are well-tested, follow our coding standards, and include relevant documentation if necessary.
Reference Issues:
If your PR addresses an existing issue, include refs #<issue-number> or fixes #<issue-number> in your PR description.

Our maintainers will review your pull request and provide feedback. We aim to make the review process as smooth and timely as possible.

Commit Message Guidelines

We follow the Conventional Commits standard. Your commit messages should have the following format:

<type>[optional scope]: <description>

Types may include:
- feat – a new feature
- fix – a bug fix
- docs – documentation changes
- style – code style changes (formatting, missing semicolons, etc.)
- refactor – code changes that neither fix a bug nor add a feature
- test – adding or correcting tests
- chore – changes to tooling, build process, etc.
- high priority – a high priority feature or fix
- high risk – a high risk feature or fix
- improvement – an improvement to the codebase

Examples:

feat(auth): add social login integration
fix(ui): correct misaligned button on homepage
docs: update installation instructions

Using clear and consistent commit messages makes it easier for everyone to understand the project history and aids in automating changelog generation.

Local Development Setup

To set up your local development environment:

Option 1: Using Docker (Recommended)

Docker provides a consistent development environment with all dependencies pre-configured.

Clone the Repository:

git clone https://github.com/<your-username>/sim.git
cd sim

Start the Docker Environment:
```
docker compose up -d
```
Or use the convenience script which handles environment setup and migrations:
```
chmod +x scripts/start_simstudio_docker.sh
./scripts/start_simstudio_docker.sh
```
This will:
- Start a PostgreSQL database container
- Build and run the Next.js application with hot-reloading
- Set up all necessary environment variables
- Apply database migrations automatically
View Logs:
```
docker compose logs -f simstudio
```
Make Your Changes:
- Edit files in your local directory
- Changes will be automatically reflected thanks to hot-reloading

Option 2: Using VS Code / Cursor Dev Containers

Dev Containers provide a consistent and easy-to-use development environment:

Prerequisites:
- Visual Studio Code
- Docker Desktop
- Remote - Containers extension for VS Code
Setup Steps:
- Clone the repository:
```
git clone https://github.com/<your-username>/sim.git
cd sim
```
- Open the project in VS Code
- When prompted, click "Reopen in Container" (or press F1 and select "Remote-Containers: Reopen in Container")
- Wait for the container to build and initialize
- The development environment will be set up in the sim/ directory
Start Developing:
- All dependencies and configurations are automatically set up
- Use the provided aliases (like sim-start) to run common commands
- Your changes will be automatically hot-reloaded
GitHub Codespaces:
- This setup also works with GitHub Codespaces if you prefer development in the browser
- Just click "Code" → "Codespaces" → "Create codespace on main"

Option 3: Manual Setup

If you prefer not to use Docker or Dev Containers:

Clone the Repository:

git clone https://github.com/<your-username>/sim.git
cd sim/sim

Install Dependencies:
- Using NPM:
```
npm install
```
Set Up Environment:
- Copy .env.example to .env
- Configure database connection and other required authentication variables
Set Up Database:
- You need a PostgreSQL instance running
- Run migrations:
```
npm run db:push
```
Run the Development Server:
- With NPM:
```
npm run dev
```
Make Your Changes and Test Locally.

License

This project is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the MIT License as well.

Adding New Blocks and Tools

Sim Studio is built in a modular fashion where blocks and tools extend the platform's functionality. To maintain consistency and quality, please follow the guidelines below when adding a new block or tool.

Where to Add Your Code

Blocks: Create your new block file under the /sim/blocks/blocks directory.
Tools: Create your new tool file under the /sim/tools directory.

In addition, you will need to update the registries:

Block Registry: Update the blocks index (usually /sim/blocks/index.ts) to include your new block.
Tool Registry: Update the tools registry (/sim/tools/index.ts) to add your new tool.

How to Create a New Block

Create a New File:
Create a file for your block (e.g., newBlock.ts) in the /sim/blocks/blocks directory.
Create a New Icon: Create a new icon for your block in the /sim/components/icons.tsx file.

Define the Block Configuration:
Your block should export a constant of type BlockConfig. For example:

import { SomeIcon } from '@/components/icons'
import { BlockConfig } from '../types'

// Define response type if needed
interface NewBlockResponse {
  output: {
    // Define expected output here
    result: string
  }
}

export const NewBlock: BlockConfig<NewBlockResponse> = {
  type: 'new',
  name: 'New Block',
  description: 'Description of the new block',
  longDescription: 'A more detailed description of what this block does and how to use it.',
  category: 'tools',
  bgColor: '#123456',
  icon: SomeIcon,

  // If this block requires OAuth authentication
  provider: 'new-service',

  // Define subBlocks for the UI configuration
  subBlocks: [
    {
      id: 'apiKey',
      title: 'API Key',
      type: 'short-input',
      layout: 'full',
      placeholder: 'Enter your API key',
    },
    {
      id: 'query',
      title: 'Query',
      type: 'long-input',
      layout: 'full',
      placeholder: 'Enter your search query',
    },
    {
      id: 'model',
      title: 'Model',
      type: 'dropdown',
      layout: 'half',
      options: ['model-1', 'model-2', 'model-3'],
    },
  ],
}

Register Your Block:
Import and add your block to the blocks registry (/sim/blocks/index.ts) in the appropriate index file so it appears in the workflow builder.

import { NewBlock } from './blocks/newBlock'

export const blocks = [
  // ... existing blocks
  NewBlock,
]

export const blocksByType: Record<string, BlockConfig> = {
  // ... existing blocks by type
  new: NewBlock,
}

Test Your Block:
Ensure that the block displays correctly in the UI and that its functionality works as expected.

How to Create a New Tool

Create a New Directory:
For tools with multiple related functions, create a directory under /sim/tools (e.g., /sim/tools/newService).
Create Tool Files:
Create files for your tool functionality (e.g., read.ts, write.ts) in your tool directory.

Create an Index File:
Create an index.ts file in your tool directory that imports and exports all tools with appropriate prefixes:

import { readTool } from './read'
import { writeTool } from './write'

export const newServiceReadTool = readTool
export const newServiceWriteTool = writeTool

Define the Tool Configuration:
Your tool should export a constant of type ToolConfig. For example:

import { ToolConfig, ToolResponse } from '../types'

interface NewToolParams {
  apiKey: string
  query: string
}

interface NewToolResponse extends ToolResponse {
  output: {
    result: string
  }
}

export const readTool: ToolConfig<NewToolParams, NewToolResponse> = {
  id: 'new_service_read',
  name: 'New Service Reader',
  description: 'Description for the new tool',
  version: '1.0.0',

  // OAuth configuration (if applicable)
  provider: 'new-service', // ID of the OAuth provider
  additionalScopes: ['https://api.newservice.com/read'], // Required OAuth scopes

  params: {
    apiKey: {
      type: 'string',
      required: true,
      description: 'API key for authentication',
    },
    query: {
      type: 'string',
      required: true,
      description: 'Query to search for',
    },
  },
  request: {
    url: 'https://api.example.com/query',
    method: 'POST',
    headers: (params) => ({
      'Content-Type': 'application/json',
      Authorization: `Bearer ${params.apiKey}`,
    }),
    body: (params) => JSON.stringify({ query: params.query }),
  },
  transformResponse: async (response: Response) => {
    const data = await response.json()
    return {
      success: true,
      output: { result: data.result },
    }
  },
  transformError: (error) => {
    return error.message || 'An error occurred while processing the tool request'
  },
}

Register Your Tool:
Update the tools registry in /sim/tools/index.ts to include your new tool. Import from your tool's index.ts file:

import { newServiceReadTool, newServiceWriteTool } from './newService'
// ... other imports

export const tools: Record<string, ToolConfig> = {
  // ... existing tools
  new_service_read: newServiceReadTool,
  new_service_write: newServiceWriteTool,
}

Test Your Tool:
Ensure that your tool functions correctly by making test requests and verifying the responses.

Guidelines & Best Practices

Code Style: Follow the project's ESLint and Prettier configurations. Use meaningful variable names and small, focused functions.
Documentation: Clearly document the purpose, inputs, outputs, and any special behavior for your block/tool.
Error Handling: Implement robust error handling and provide user-friendly error messages.
Testing: Add unit or integration tests to verify your changes when possible.
Commit Changes: Update all related components and registries, and describe your changes in your pull request.

Happy coding!

Thank you for taking the time to contribute to Sim Studio. We truly appreciate your efforts and look forward to collaborating with you!

14 KiB Raw Blame History Unescape Escape