Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
316 lines (212 loc) · 9.09 KB

CONTRIBUTING.md

File metadata and controls

316 lines (212 loc) · 9.09 KB

Contributing to Bubble Lab - Important Notice

⚠️ UPDATE (January 20, 2026): We are no longer accepting contributions to this project at this time. Thank you to everyone who has contributed and shown interest in Bubble Lab.

Contributing to Bubble Lab (Prior to Jan 20, 2026)

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

Definition of Done

For a PR to be merged, it must:

  • Align with Bubble Lab’s existing architecture and patterns
  • Avoid introducing new abstractions unless clearly justified
  • Pass all tests, lint, and type checks
  • Include tests for new behavior (when applicable)
  • Update documentation if user-facing behavior changes
  • Keep changes scoped and easy to review

If a PR requires large structural changes, please open an issue or discussion first.

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

Project Direction & Review Philosophy

Bubble Lab prioritizes:

  • Simplicity over clever abstractions
  • Consistency with existing patterns
  • Long-term maintainability over short-term feature velocity

Not all contributions will be merged. A pull request may be closed if:

  • The feature does not align with the current roadmap or architecture
  • The implementation adds unnecessary complexity
  • The change would require significant maintainer refactoring
  • The PR is too large to review safely without prior discussion

Closed PRs are not a reflection of contributor quality — they help us keep the codebase healthy and move fast.

Need Help?

Thank you for contributing to Bubble Lab! 🎉