Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
282 lines (190 loc) · 7.78 KB

CONTRIBUTING.md

File metadata and controls

282 lines (190 loc) · 7.78 KB

Contributing to Bubble Lab

Thank you for your interest in contributing to Bubble Lab! We welcome all kinds of contributions from the community. AI-powered search tools such as Cursor's ask mode can significantly speed up the process of understanding each part of the codebase.

📋 Table of Contents

Getting Started

Before contributing, please:

  • Join our Discord community for discussions and support
  • Check existing issues or open a new one to discuss your idea
  • Read through this guide to set up your development environment

Prerequisites

Make sure you have the following installed:

  • Bun - Required for running the backend API server
  • pnpm - Package manager for monorepo management
  • Node.js - v18 or higher

Development Setup

Quick Setup (Mac/Linux)

Run Bubble Studio locally in 2 commands:

# 1. Install dependencies
pnpm install

# 2. Start everything
pnpm run dev

That's it! The setup script automatically:

  • ✅ Creates .env files from examples
  • ✅ Configures dev mode (no auth required)
  • ✅ Sets up SQLite database
  • ✅ Builds core packages
  • ✅ Starts both frontend and backend

Open http://localhost:3000 and start building workflows!

What Gets Started

Windows Setup (Separate Steps)

Some scripts use Unix commands (cp, bash), so Windows requires manual steps:

1. Install Dependencies

pnpm install

2. Build Core Packages

pnpm build:core

3. Copy Required Files

Copy-Item "packages/bubble-core/dist/bubble-bundle.d.ts" "apps/bubble-studio/public/bubble-types.txt" -Force
Copy-Item "packages/bubble-core/dist/bubbles.json" "apps/bubble-studio/public/bubbles.json" -Force

4. Start Servers (Two Terminals)

Terminal 1 – Backend (API):

cd apps/bubblelab-api
& "$env:USERPROFILE\.bun\bin\bun.exe" run src/index.ts

Terminal 2 – Frontend (Studio):

cd apps/bubble-studio
pnpm vite --host 0.0.0.0 --port 3000

⚠ If you get "TypeScript validation failed," rebuild core packages.

Environment Configuration

Required API Keys

⚠️ IMPORTANT: To run any flows in self-hosted mode, you MUST configure these API keys in apps/bubblelab-api/.env:

GOOGLE_API_KEY=your_google_api_key        # Required for AI flow execution
OPENROUTER_API_KEY=your_openrouter_key    # Required for AI flow execution

Without these keys, you can use the visual builder but cannot execute flows. Get your keys:

Environment Files

The setup script creates these files with sensible defaults:

apps/bubble-studio/.env:

VITE_API_URL=http://localhost:3001
VITE_CLERK_PUBLISHABLE_KEY=
VITE_DISABLE_AUTH=true  # Dev mode: no auth needed

apps/bubblelab-api/.env:

BUBBLE_ENV=dev  # Creates mock user automatically
DATABASE_URL=file:./dev.db  # SQLite

Optional API Keys

Enable specific features in apps/bubblelab-api/.env:

# AI Model Providers
OPENAI_API_KEY=           # OpenAI API key for GPT models

# Communication & Storage
RESEND_API_KEY=           # Resend API key for email notifications
FIRE_CRAWL_API_KEY=       # FireCrawl API key for web scraping

# Authentication (optional, only needed for production mode)
CLERK_SECRET_KEY_BUBBLELAB=  # Clerk secret key for authentication

# OAuth (optional)
GOOGLE_OAUTH_CLIENT_ID=      # Google OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET=  # Google OAuth client secret

# Cloud Storage (optional)
CLOUDFLARE_R2_ACCESS_KEY=    # Cloudflare R2 access key
CLOUDFLARE_R2_SECRET_KEY=    # Cloudflare R2 secret key
CLOUDFLARE_R2_ACCOUNT_ID=    # Cloudflare R2 account ID

# Other
PYTHON_PATH=              # Custom Python path (optional)
CREDENTIAL_ENCRYPTION_KEY=8VfrrosUTORJghTDpdTKG7pvfD721ChyFt97m3Art1Y=  # Encryption key for storing user credentials
BUBBLE_CONNECTING_STRING_URL=  # Database connection string (optional, defaults to SQLite)

Development vs Production Mode

Development Mode (Default)

By default, the app runs in development mode with:

  • 🔓 No authentication required - Uses mock user dev@localhost.com
  • 💾 SQLite database - Auto-created at apps/bubblelab-api/dev.db
  • 🎯 Auto-seeded dev user - Backend creates the user automatically

Production Mode

To run with real authentication:

  1. Get your Clerk keys at clerk.com
  2. Update .env files:

Frontend (apps/bubble-studio/.env):

VITE_CLERK_PUBLISHABLE_KEY=pk_test_...
VITE_DISABLE_AUTH=false

Backend (apps/bubblelab-api/.env):

BUBBLE_ENV=prod
CLERK_SECRET_KEY=sk_test_...
  1. Restart with pnpm run dev

Available Commands

# Run only the setup script
pnpm run setup:env

# Start development servers
pnpm run dev

# Build for production
pnpm run build

# Run tests
pnpm test

# Lint code
pnpm lint

Project Architecture

BubbleLab is built on a modular monorepo architecture:

Core Packages

Apps

Deployment

For Docker-based deployment instructions, see deployment/README.md.

Contribution Guidelines

We welcome all types of contributions:

Ways to Contribute

  • 🐛 Bug Reports - Open an issue with detailed reproduction steps
  • ✨ Feature Requests - Suggest new features or improvements to Bubble Studio
  • 🔧 Code Contributions - Fix bugs or implement new features
  • 🧩 New Bubbles - Add new integrations, tools, or logic nodes
  • 📚 Documentation - Improve guides, examples, or API docs
  • 💬 Community Support - Help others in Discord or GitHub discussions

Pull Request Process

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes following the coding standards
  4. Test your changes thoroughly
  5. Commit your changes with clear, descriptive messages
  6. Push to your fork and submit a pull request
  7. Wait for review and address any feedback

Coding Standards

  • Use TypeScript with proper types (no any)
  • Follow existing code style and conventions
  • Write tests for new features
  • Update documentation as needed
  • Keep commits atomic and well-described

Need Help?

Thank you for contributing to Bubble Lab! 🎉